=====
Forms
=====

One of the key concepts of the framework is the concept of form.

When the user clicks the menu item of the main menu, the 
:doc:`view </refs/client/item/m_view>`
method of the corresponding item is executed, which creates the view form.

This view form can have the **New** and **Edit buttons**, clicking on which
the
:doc:`insert_record </refs/client/item/m_insert_record>`
and
:doc:`edit_record </refs/client/item/m_edit_record>` 
methods will be executed. These methods create an item edit form.

Forms are based on HTML 
:doc:`form templates <form_templates>`
that determine their layout. Form templates are defined in the
:doc:`Index.html <index_html>`
file, located in the root folder of the project.

The application already has default templates for viewing and editing data, 
for specifying filters and report parameters.

For example, all edit forms of the Demo project use the following html template:

.. code-block:: html

  <div class="default-edit">
      <div class="form-body">
          <div class="edit-body"></div>
          <div class="edit-detail"></div>
      </div>
      <div class="form-footer">
          <button type="button" id="ok-btn" class="btn expanded-btn">
              <i class="icon-ok"></i> OK<small class="muted">&nbsp;[Ctrl+Enter]</small>
          </button>
          <button type="button" id="cancel-btn" class="btn expanded-btn">
              <i class="icon-remove"></i> Cancel
          </button>
      </div>
  </div>

You can define your own form templates to create your own custom forms. See 
:doc:`Form templates <form_templates>`

When some method creates a form the application finds corresponding html template. 

If ``container`` (a Jquery object) parameter is specified, the method empties it 
and appends the html template to it, otherwise, it creates an empty modal form 
and appends the template to the form. 

After this it assigns item's ``prefix_form`` 
attribute to the template, triggers an ``on_prefix_form_created`` events, 
shows the form and triggers ``on_prefix_form_shown`` events, where prefix is a 
type of the form (view, edit, filter, param). 
See :doc:`Form events <form_events>` for details.

Below is an example of the ``on_edit_form_created`` event handler of the task:

.. code-block:: js

  function on_edit_form_created(item) {
      item.edit_form.find("#ok-btn").on('click.task', function() { item.apply_record() });  
      item.edit_form.find("#cancel-btn").on('click.task', function(e) { item.cancel_edit(e) });

      if (!item.master && item.owner.on_edit_form_created) {
          item.owner.on_edit_form_created(item);
      }
      if (item.on_edit_form_created) {
          item.on_edit_form_created(item);
      }
      
      item.create_inputs(item.edit_form.find(".edit-body"));
      item.create_detail_views(item.edit_form.find(".edit-detail"));
  
      return true;
  }

In this example, the the ``find`` method  of JQuery is used to to find 
elements on the form. 

First, we assign a JQuery ``click`` event to **OK** and **Cancel** buttons,    
so 
:doc:`cancel_edit </refs/client/item/m_cancel_edit>`
and
:doc:`apply_record </refs/client/item/m_apply_record>` methods will be executed 
when user clicks on the buttons. This methods cancel or apply changes made to 
the record respectively and call the 
:doc:`close_edit_form </refs/client/item/m_close_edit_form>`
method to close the form.

Then, if item is not a detail and has an event handler ``on_edit_form_created``, 
defined in the owner's client module, this event handler is executed.

After that, if item has an event handler ``on_edit_form_created``, 
defined in the item's client module, this event handler is executed.

In these event handlers some additional actions could be executed.
For example you can assign click events to buttons or some other elements
contained in your edit form template, change
:doc:`edit_options </refs/client/item/at_edit_options>`,
create tables using the
:doc:`create_table </refs/client/item/m_create_table>`
method and so on.


Then 
the
:doc:`create_inputs </refs/client/item/m_create_inputs>`
method is called to create inputs in the element with class "edit-body"

Finally, 
:doc:`create_detail_views </refs/client/item/m_create_detail_views>`
method is called to create details in the element with class "edit-detail"

.. note::

  If some elements are missing in the form template, an exception will not be raised.

The ``close_prefix_form``, where ``prefix`` is the type of the form, closes the
form of this type. But before form is closed the ``on_prefix_form_close_query`` 
and ``on_prefix_form_closed`` events are triggered. After form is closed it is 
removed from the DOM.