.. -*- coding: utf-8 -*-
.. :Project:  arstecnica-webix -- commentary on the code
.. :Created:  lun 23 gen 2017 15:40:14 CET
.. :Author:   Alberto Berti <alberto@metapensiero.it>
.. :License:  GNU General Public License version 3 or later
..

.. default-domain:: js

==============
 Proxy object
==============

A proxy object is a normal JavaScript object with a flag ``$proxy`` member set
to ``true``. The available doc on webix site can be found `here`__, but it
doesn't explain so much about the internals of loading and saving
process. I can implement the following functions:

__ http://docs.webix.com/desktop__server_proxy.html

.. js:function:: proxy.load(view, callback)

   It's called by a data-bound component to fill in with the data values.

   :param Object view: This is the calling object, it can be a view in the
       strict sense of the term, or a `~webix.DataCollection`:class: component
       or anything that is extended with `~webix.AtomDataLoader`:class: mixin.

   :param Object callback: An object passed in by the calling context that has
       the ``success`` and ``error`` members. It is tailored to be passed to
       an AJAX call.

.. js:function:: proxy.save(view, update, dp, callback)

   It's called by a `~webix.DataProcessor`:class: object which is in turn
   bound via a ``master`` configuration member to the same object that calls
   the `~proxy.load`:func: function. If there's no
   `~webix.DataProcessor`:class: connected, this will never be called.

   :param Object view: This is the calling object, it can be a view in the
       strict sense of the term, or a `~webix.DataCollection`:class: component
       or anything that is extended with `~webix.AtomDataLoader`:class: mixin.

   :param Object update: Contains the actual data to be submitted to the
       server. The record is in a ``data`` member and the kind of operation to
       be performed is in the ``operation`` member that can have the values
       ``insert``, ``update``, ``delete``.

   :param dp: The linked processor, the actual context that is calling this
       method.
   :type dp: `~webix.DataProcessor`:class:

   :param Object callback: An object passed in by the calling context that has
       the ``success`` and ``error`` members. It is tailored to be passed to
       an AJAX call.


DataCollection loading process
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The code executed to load the data from the proxy for a component like the
`~webix.DataCollection`:class: is scattered among many components and
mixins. This a tentative to have better understanding of how that happens in
the context of building a data layer for Ytefas.

The basic code is in `~webix.AtomDataLoader`:class: mixin that uses a
`~webix.DataDriver`:class: instance (a `~webix.DataDriver.json`:class: by
default) to recognize key elements of the data. This is extended by
`~webix.DataLoader`:class: mixin which adds storage support using an instance
of the `~webix.DataStore`:class: component. This is in turn extended by the
`~webix.DataCollection`:class: code which unifies this feature with ``sync()``
and ``bind()`` implementations and cursor management.