======
insert
======

.. js:function:: insert()

**domain**: client 

**language**: javascript

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

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

Inserts a new, empty record in the item dataset.

After a call to ``insert``, an application can enable users to enter data in the 
fields of the record, and can then post those changes to the item dataset using 
:doc:`post <m_post>` 
method, and then apply them to the item database table, using 
:doc:`apply <m_apply>` 
method. 

The ``insert`` method

* checks if item dataset is 
  :doc:`active <at_active>`
  , otherwise raises exception

* if the item is a 
  :doc:`detail </programming/data/details>`
  , checks if the master item is in edit or insert 
  :doc:`state <at_item_state>`
  , otherwise raises exception

* if the item is not a 
  :doc:`detail </programming/data/details>`
  checks if it is in browse 
  :doc:`state <at_item_state>`
  , otherwise raises exception

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

* inserts a new, empty record in the item dataset.

* puts the item into insert 
  :doc:`state <at_item_state>`

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

* updates 
  :doc:`data-aware controls </programming/interface/data_controls>`

See also
========

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