=====
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 and ``async`` parameter is ``false`` 
  or ``undefined``, the request to the server is 
  sent synchronously, otherwise, the request is executed asynchronously and 
  after the response 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 (the master saves the
  details changes)

* 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, 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, see also
  :doc:`on_apply events </programming/server/on_apply_events>` topic
  
* 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 the client throws an 
  exception, before throwing exception, if the callback parameter is passed, 
  it is called and the error is passed as the callback function parameter

* 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. 

.. 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 can
    update them yourself using, for example, 
    :doc:`refresh_record <m_refresh_record>`
    method
    
Example
=======


.. code-block:: js

  var self = this;
  this.apply(function(err) {
      if (err) {
          self.alert_error(err);
      }
      else {
          //some code to execute after appling changes
      }
  });



See also
========

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