frappe/docs/old/_sources/listing.txt

Listing
=======

The listing widget is used to show a list of values from the server. It is a widget that is completely
scripted and gets the list from a plug-in SQL query. It also has many viewing and customizing options
and manages paging of results.

Listing Options
---------------

Features of a Listing widget can be controlled by setting the `opts` properties before calling the
`make` function. The default Listing options are::

   list_opts = {
      cell_style : {padding:'3px 2px'},

      // style for alternate row
      alt_cell_style : {backgroundColor:'#F2F2FF'}, 

      // style for header
      head_style : {height:'20px',overflow:'hidden',verticalAlign:'middle',textAlign:'center',fontWeight:'bold',padding:'1px',fontSize:'13px'}
      head_main_style : {padding:'0px'},

      // buttons
      hide_export : 0,
      hide_print : 0,
      hide_refresh : 0,
      hide_rec_label: 0,
      show_calc: 1,
      
      // clear tab on "refresh"
      show_empty_tab : 1,
      show_bottom_paging: 1,
      no_border: 0
   };

Listing Class
-------------

.. class:: Listing(head_text, no_index, no_loading)

   `head_text` is the header of the widget, `no_index` means that the "Serial No" is not to be shown and
   `no_loading` means the "Loading..." spinner is to be hidden while the query is executed.
   
   .. attribute:: page_len
   
      Length of one page output. Default 20
      
   .. attribute:: paging_len
   
      Number of page pointers to be shown. Default 5

   .. attribute:: head_text
   
      Text to be shown at the heading. Default "Results"
      
   .. attribute:: keyword
   
      Keyword for each record. Default "records"
      
   .. attribute:: colnames
   
      List of column labels

   .. attribute:: coltypes
   
      List of column types

   .. attribute:: colwidths
   
      List of column widths. 
      
      **The listing only shows as many columns as specified in the `colwidths`**

   .. attribute:: coloptions
   
      List of column options. (Useful in case type is `Link`)
      
   .. attribute:: filters
   
      Dictionary of filter objects
      
   .. attribute:: is_std_query
   
      If this is true, it will add `match` permissions automatically. The query must be in :term:`Standard Query`
      format.
      
  .. method:: make(parent)
  
     Create the UI in the given `parent` Element. All filters must be added before this method is called
     
  .. method:: add_filter(label, ftype, options, tname, fname, cond)
  
     Add a filter input widget to the listing. See example
     
  .. method:: remove_filter(label)
  
     Remove a filter
     
  .. method:: remove_all_filters()
  
     Remove all filters
     
  .. method:: add_sort(column_index, fname)
  
     Add a sorting feature to a particular column
     
  .. method:: set_default_sort(fname, sort_order)
  
     Set the default sort property
     
  .. method:: run()
  
     Execute the query
     
  .. method:: std_cell(d, ri, ci)
  
     Render the standard output in the cell, `d` is the resultset, `ri` and `ci` are row index and 
     column index

Creating a Listing
------------------

To create a listing,

* Restrict the number of columns generated by specifying the `colwidths`
* Optionally declare `colnames`, `coltypes` and `coloptions`
* Declare the `get_query` method that will declare 2 queries
  * `query`
  * `query_max`
* To customize the output, declare the `show_cell(cell, ri, ci, d)` method to render the cell content. 

See examples below

Examples
--------

Example of a customized listing::

   // create a new listing
   var lst = new Listing();
   
   // define the columns etc
   lst.colwidths = ['5%','30%','15%','15%','20%','5%','10%'];
   lst.colnames = ['Sr.','Email','Status','','','',''];
   lst.coltypes = ['Data','Data','','','','',''];
   lst.coloptions = ['','','','','','',''];
   
   // define options   
   var opts = {};
  
   opts.head_main_style = {};  
   opts.cell_style = { padding:'3px 2px', borderRight : '0px', borderBottom : '1px solid #AAA'}
   opts.head_style = { padding:'3px 2px', borderBottom : '1px solid #AAA'}
   opts.alt_cell_style = {};
   opts.hide_print = 1;
   opts.no_border = 1;    
  
   lst.opts = opts;
  
   // define the query
   lst.get_query = function(){
      
      // write your own query here
      this.query = repl("select name, enabled from ... where ... ");
      this.query_max = repl("select count(*) from ... where ...");
   }
   
   //show cell - customize output
   lst.show_cell = function(cell,ri,ci,d){
      if (ci==1){
         if (d[ri][ci]==1){
            var hl=$a(cell,'span','Data');
            hl.innerHTML = 'Enabled';
            $y(hl,{color:'GREEN'});
            
         }
         else if (d[ri][ci]==0){
            var hl=$a(cell,'span','Data');
            hl.innerHTML = 'Disabled';
         }
      } else{
      	
      	// show standard output
        lst.std_cell(d,ri,ci);  
      }
   }
   
   // add filters
   lst.add_filter('Type', 'Select', ['','Old','New'].join(NEWLINE), 'Profile', 'user_type', '=');
   
   // generate
   lst.make(parent);