=======
on_open
=======

on_open(item, params)

**domain**: server

**language**: python

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

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

Write ``on_open`` event handler when you need to override the standard 
procedure of fetching the records from the dataset during the execution of the 
open method on the
:doc:`client </refs/client/item/m_open>`
or
:doc:`server <m_open>`.

See
:doc:`on_open_events </programming/server/on_open_events>`
to understand how on_open events are triggered.


The ``on_open`` event handler has the following parameters:

* ``item`` - reference to the item,

* ``params`` - dictionary containing parameters passed to the server by the open 
  method:

  * ``__expanded`` - corresponds to the ``expanded`` parameter of the server 
    :doc:`open <m_open>` method / ``expanded`` attribute of options parameter of
    the client 
    :doc:`open </refs/client/item/m_open>`
    method
    
  * ``__fields`` - list of field names
  
  * ``__filters`` - list of items, each of which is a list with the following members:
  
    * field name
    * filter constant from :doc:`Filtering records </programming/data/filtering_records>`
    * filter value
    
  * ``__funcs`` - functions dictionary
  
  * ``__order`` - list of items, each of which is a list with the following members:
  
    * field name
    * boolen value, if it is true the order is descending
  
  * ``__offset`` - corresponds to the offset parameter of the open method
  
  * ``__limit`` - corresponds to the limit parameter of the open method  
  
  * ``__client_request`` - is true when request came from the client
  
  ``params`` can also include user defined parameters passed to the open method.
  
Below is an example of params that the client open methods of invoices items 
sends to the server: 

.. code-block:: py  

  {
      '__fields': [u'id', u'deleted', u'customer', u'firstname', u'date',
          u'subtotal', u'taxrate', u'tax', u'total',
          u'billing_address', u'billing_city', u'billing_country',
          u'billing_postal_code', u'billing_state'],
      '__filters': [[u'customer', 7, [6]]],
      '__expanded': True,
      '__limit': 11,    
      '__offset': 0,
      '__order': [[u'date', True]]
  }
  
  {
      '__fields': [u'id'],
      '__funcs': {u'id': u'count'},
      '__filters': [],
      '__expanded': False,
      '__offset': 0,
      '__order': [],
      '__summary': True
  }

The server application generates an SQL query, based on params and executes them. 

The server returns to the client the resulting records and the error message if 
it occurs during the execution.

:doc:`Here is an example how server events can be used </how_to/how_to_multitenancy>`

See also
========

:doc:`on_open_events </programming/server/on_open_events>`

:doc:`Server side programming </programming/server/index>`

:doc:`Dataset </programming/data/dataset>`

