=============
table_options
=============

.. js:attribute:: table_options

**domain**: client 

**language**: javascript

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

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

The ``table_options`` attribute is a set of options that determine how the table
of the view form of will be displayed. Options defined in it are used by the
:doc:`create_table <m_create_table>`
method if its options parameter don't override corresponding option.

These options are set in the **Layout** tab of the
:doc:`View Form Dialog </admin/items/view_form_dialog>`
in Application Builder.

You can change ``table_options`` in the 
:doc:`on_view_form_created <on_view_form_created>`
event handler of the item. See example.

The ``table_options`` parameter is an object that may have the following attributes:

=================== ============================================================
Option              Description
=================== ============================================================
row_count           specifies the number of rows displayed by the table

height              if row_count is not specified, it determines the height of 
                    the table, the default value is 480. The table at creation 
                    calculates the number of rows displayed (row_count), 
                    based on the value of this parameter.

fields              a list of field names. If specified, a column will be 
                    created for each field whose name is in this list, if not 
                    specified (the default) then the fields attribute of an 
                    :doc:`view_options <at_view_options>`
                    will be used 
                    
title_line_count    specifies the number of lines of text displayed in a 
                    title row, if it is 0, the height of the row is determined 
                    by the contents of the title cells                

row_line_count      specifies the number of lines of text displayed in a 
                    table row, if it is 0, the height of the row is determined 
                    by the contents of the cells

expand_selected_row if row_line_count is set and expand_selected_row is 
                    greater that 0, it specifies the minimal number of lines of 
                    text displayed in the selected row of the table

title_word_wrap     specifies if the column title text can be wrapped.

column_width        the width of the columns are calulated by a Web Browser. 
                    You can use this option to force the width of columns. The option is an 
                    object, key values of which are field names, the values are column widths
                    as CSS units
  
editable_fields     the list of field names could be edited in the table. 

selected_field      if editable_fields are set, specifies the name of the
                    field whose column will be selected, when the selected row 
                    is changed.

sortable            if this option is specified, it is possible to sort the 
                    records by clicking on the table column header. When a 
                    sort_fields option is not specified (default), a user can 
                    sort records on any field, otherwise, only on the fields 
                    whose names are listed in this option.

sort_fields         the list of field names on which the table can be sorted,
                    by clicking on the corresponding table column header.
                    If an item is a detail the operation is performed on the 
                    client, otherwise sorting is performed on the server (the 
                    :doc:`open <m_open>`
                    method is used internally).

summary_fields      a list of field names. When it is specified, the table 
                    calculates sums for numeric fields and displays them in the 
                    table footer, for not numeric fields it displays the number 
                    of records.

freeze_count        an integer value. If it is greater than 0, it specifies 
                    number of first columns that become frozen - they will not 
                    scroll when the table is scrolled horizontally.
 
show_hints          if true, the tooltip will be displayed when the user hovers 
                    the mouse over a table cell, and the cell text does not fit 
                    in the cell size. The default value is true.
  
hint_fields         a list of field names. If it is specified, the tooltip will 
                    be displayed only for fields from this list, regardless of 
                    the value of show_hints option value.

on_click            specifies the function, that will be executed when a user 
                    click on a table row. The item will be passed as a parameter 
                    to the function. 

on_dblclick         specifies the function, that will be executed when a user 
                    double click on a table row. The item will be passed as a 
                    parameter to the function. 

dblclick_edit       if the value of the option is set to true and the 
                    on_dblclick option is not set, the edit form will be shown 
                    when a user double click on a table row. 

multiselect         if this option is set, a leftmost column with check-boxes 
                    will be created to select records. So, that when a user 
                    clicks on the check-box, the value of the primary key field 
                    of the record will be added to or deleted from the 
                    :doc:`selections <at_selections>` attribute.
  
select_all          if  true, the menu will appear in the leftmost column of 
                    the table header, which will allow the user selects all 
                    records that match the current filters and the search value.

row_callback        the callback functions called each time fields of the record
                    are changed. Two parameters are passed to the function - 
                    item, whose record has changed and JQuery object of the 
                    corresponding row of the table. Please be carefull - the 
                    item passed to the function can be not item itself, but its 
                    clone that share the same dataset.
=================== ============================================================  


Example
=======

.. code-block:: js

  function on_view_form_created(item) {
      item.table_options.row_line_count = 2;
      item.table_options.expand_selected_row = 3;    
  }

The code in the following two examples does the same:

.. code-block:: js

  item.invoice_table.create_table(item.view_form.find('.view-detail'), {
      height: 200,
      summary_fields: ['date', 'total'],
  });

.. code-block:: js

  item.invoice_table.table_options.height = 200;
  item.invoice_table.table_options.summary_fields = ['date', 'total'];
  item.invoice_table.create_table(item.view_form.find('.view-detail'));


See also
========

:doc:`View Form Dialog </admin/items/view_form_dialog>`

:doc:`on_view_form_created <on_view_form_created>`

:doc:`create_table <m_create_table>`
