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

.. py:method:: insert(self)

**domain**: server

**language**: python

**class** :doc:`Item class </refs/server/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 ``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 ``on_after_append`` event handler if one is defined for the item.

See also
========

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