==========
selections
==========

.. js:attribute:: selections

**domain**: client 

**language**: javascript

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

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

The ``selections`` attribute stores a list of a primary key field values.

When a **Multiple selection** check box is checked on the 
**Layout** tab in the
:doc:`View Form Dialog </admin/items/view_form_dialog>` or
multiselect attribute of the
:doc:`table_options <at_table_options>` is set programmatically,
the check box in the leftmost column of the table appears and
each time a user clicks on the check box, the ``selections`` attrubute changes.

It can also be changed programmatically by using ``add`` or ``remove`` methods
or assigning an array.

Example
=======

In this example, the ``send_email`` function, on the client, uses **Customers** selection 
attribute to get array of primary key field values selected by users and send them
to the ``send_email`` function defined in the server module of the item using
the
:doc:`server </refs/client/abstr_item/m_server>`
method

.. code-block:: js

  function send_email(subject, message) {
      var selected = task.customers.selections;
      if (!selected.length) {
          selected.add(task.customers.id.value);
      }
      
      item.server('send_email', [selected, subject, message], 
          function(result, err) {
              if (err) {
                  item.alert('Failed to send the mail: ' + err);
              }
              else {
                  item.alert('Successfully sent the mail');
              }
          }
      );
  }
  
On the server, this array is used to retrieve information about selected customers
using 
:doc:`open </refs/server/item/m_open>`
method

.. code-block:: py

  import smtplib
  
  def send_email(item, selected, subject, mess):
      cust = item.task.customers.copy()
      cust.set_where(id__in=selected)
      cust.open()
      to = []
      for c in cust:
          to.append(c.email.value)
          
      # code that sends email