========
on_login
========

on_login(task, form_data, info)

**domain**: server

**language**: python

**class** :doc:`Task class </refs/server/task_api>`

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

Use ``on_login`` to override default login procedure using Application
Builder Users table.

``task`` parameter is a reference to the 
:doc:`task tree </programming/task_tree>`.

``form_data`` is a dictionary containing the values that the user entered in 
the inputs in the login form. The keys of the dictionary are name attributes
of the inputs.

``info`` parameter is a dictionary with the following attributes: 

* ``ip`` is the ip address of the request 
* ``session_uuid`` is uuid of the session that will be created.

The event handler must return the dictionary with the following attributes:

* ``user_id`` - the unique id of the user
* ``user_name`` - user name
* ``role_id`` - ID of the role defined in the 
  :doc:`Roles </admin/roles>`
* ``role_name`` - role name

The login form is located in the 
:doc:`index.html </programming/interface/index_html>`
file. You can add your own
custom inputs and get their values using form_data parameter

.. code-block:: html

  <form id="login-form" target="dummy" class="form-horizontal" data-caption="Log in">
      <div class="control-group">
          <label class="control-label" for="input-login">Login</label>
          <div class="controls">
              <input type="text" id="input-login" name="login" tabindex="1" placeholder="login">
          </div>
      </div>
      <div class="control-group">
          <label class="control-label" for="input-password">Password</label>
          <div class="controls">
              <input type="password" id="input-password" name="password" tabindex="2" 
                  placeholder="password" autocomplete="on">
          </div>
      </div>
      <div class="form-footer">
          <input type="submit" class="btn expanded-btn pull-right" id="login-btn" value="OK" tabindex="3">
      </div>
  </form>


Example
=======

In this example user information is stored in the table of the **Users** item in the
project database:

.. code-block:: py

  def on_login(task, form_data, info): 
      users = task.users.copy(handlers=False)
      users.set_where(login=form_data['login'])
      users.open()
      if users.rec_count == 1:
          if task.check_password_hash(users.password_hash.value, form_data['password']):
              return {
                  'user_id': users.id.value,
                  'user_name': users.name.value,
                  'role_id': users.role.value,
                  'role_name': users.role.display_text
              }
       
See also
========

:doc:`session </refs/server/abstr_item/at_session>`

:doc:`environ </refs/server/abstr_item/at_environ>`

:doc:`generate_password_hash <m_generate_password_hash>`

:doc:`check_password_hash <m_check_password_hash>`