3. Search and advanced filters

Searching in grid like Google or by formula expression

• Search provides advanced searching and filtering in grid.
  It provides three methods of searching (search like Google, search by expression and exact string search).
  The results can be shown by four actions (Filter, Select, Mark (color) and Find (focus)).
  The search can be controlled by users in <Search> row.
  

• Search setting

  
  Predefined search is set by Cfg attributes SearchExpression and SearchAction.
  

  • SearchExpression

    is the string to look for.
    Its format depends on method selected by Cfg attribute SearchMethod.
    By default the search method (1 or 2) is automatically recognized from the input SearchExpression.
    
    • 1

      Search like Google

      
      The SearchExpression has similar syntax like Google search expression. The possible syntax is:
      word word (both words must be present), "word word" (exact phrase), word OR word (at least one word must be present), -word (the word must not be present), # (empty string).
    • 2

      Search by expression

      
      It uses similar syntax to TreeGrid formulas or actions and it supports also all JavaScript.
      It can execute any JavaScript code except function calls (due security reason).
      For more information about the syntax see documentation for SearchExpression.
    • 3

      Exact string search

      
      It looks for the string as it is entered, without any processing or special syntax.

  • SearchAction

    is the action done for the found rows / cells.
    There can be listed more actions, comma or semicolon separated, done in the given order.

    • Filter

      
      It shows only the found rows. The filtering options are descibed in the previous examples 01-Filtering_rows.html and 02-Filtering_in_tree.html.

    • Select

      
      All the found rows are selected. All previously selected rows are unselected.
      If set SearchExpand='1', it expands all parent rows to become the found row visible.
      

    • Mark

      
      All the found rows or individual cells (according to SearchCells value) are colored by special background color.
      If there are some rows/cells already marked and the Mark action is done with different expression, the old colors are preserved and for new coloring is used different color.
      How many different colors can be used is set SearchMaxMark value. After the maximum is reached, all the colored rows/cells are cleared and the coloring starts from the first color.
      If set SearchClass='1', it changes also CSS class of the found cells/rows, e.g. to change font or border. It can slow down the coloring.
      If set SearchExpand='1', it expands all parent rows to become the found row visible.
      

    • Find

      
      The first found row is focused. If set SearchCells='1', it focuses the first found cell, otherwise it does not change actually focused column.
      When the Find action is run again with the same expression, it focuses cell/row next to the cell previously focused.
      More setting can be done by SearchFocused (0 - searches always from beginning, 1 - searches from the actual position and ends on the end, 2 - like 1, but on the end continues from beginning, 3 - like 1, but on the end asks before continue from beginning.
      If there is nothing found, it can display an alert, if set SearchNotFound.
      

• SearchOptions

  
  

  • Searching strings

    
    
    • Cfg attribute

      Search CaseSensitive

      to compare the strings case sensitive. By default is off (oposite to filter/group/sort setting).
    • Cfg attribute

      SearchWhiteChars

      as list of characters to ignored when comparing. The strings are compared after these values are removed from them.
    • Cfg attribute

      SearchCharCodes

      as list of character pairs to replace the first character by the second one in all strings before comparing them. Useful for example to compare strings without punctuation in many languages.

  • Searching numbers

    
    The different ways of searching numbers is used only for cell types Int and Float and for SearchMethod='1' or '3'.
    Cfg attribute

    SearchNumbers

    specifies how the numbers will be compared, 0 - searched inside as string, 1 - exact compare of the whole value, 2 - round (the value is rounded before compare), 3 - float (decimal part is removed before compare).

  • Which columns

    
    The columns can be specified only for SearchMethod='1' or '3'. For SearchMethod='2' are always used all columns in the expression.
    Cfg attribute

    SearchCols

    specifies columns that will be searched in.
    If set Cfg attribute SearchHidden='1' it will search also in hidden columns.
    The individual columns can have set CanSearch='0' to exclude it from searching.
    

  • Which rows

    
    Which rows will be searched can be set by Cfg attribute

    SearchDefs

    , only rows with Def attribute listed here will be searched.

  • Rows or cells

    
    Attribute

    SearchCells

    specifies if individual cells will be searched.
    Value 0 means searching inside whole row. All cells together must pass the condition. For example for search expression Peter Pan, must at least one cell contain Peter and onther or the same cell must contain Pan.
    Value 1 means searching in individual cells. The cell to be find must pass the condition. For example for search expression Peter Pan, must the one cell contain both Peter and Pan.
    

• Cell value for Search

  
  Every cell can have set special value by

  FilterValue

  to use it for search instead of the cell value.
  The value can be also dynamically created by JavaScript in API event OnGetFilterValue.
  It affects also filtering, but not grouping / sorting.

• API

  
  Before searching start it is called OnSearch API event. It can return true to provide own searchnig and not the default one. For Filter actions it is called also OnFilter event.
  After searching finishes, it is called OnSearchFinish API event. For Filter action it is called also OnFilterFinish event.
  For every row it is called OnRowSearch event to let you change the result of the searching in row.
  The grid can be searched with given action by SearchRows (asynchronously) or by DoSearch (synchronously).
  

• Search user interface (<Search>)

  
  The user interface is done by Space <Search> row, but the cells for controlling search can be displayed also on any other Space row like Group or Toolbar.
  There can be also more <Search> rows in one grid with different cells. The <Search> row can also contain any other custom cells not related to searching.
  There are predefined cell names, can be put into Cells array:

  • Expression

    . Editable input cell to enter the SearchExpression. Attribute ExpressionAction specifies action(s) that will be run after the Expression is edited by a user.

  • Filter

    ,

    Select

    ,

    Mark

    ,

    Find

    ,

    Clear

    ,

    Help

    . Individual buttons to run the named search action.

  • Search

    . Button to run search action(s) specified by cell value

    Actions

    - combo to choose one or more search actions.

  • List

    . Combo with predefined expression for the SearchExpression. The expression names are set by ListDefaults, the expressions by ListExpressions. After change is done action(s) set by ListAction.

  • Cols

    . Combo to select SearchCols value. The item names are set by ColsDefaults, the values by ColsCols.

  • Defs

    . Combo to select SearchDefs value. The item names are set by DefsDefaults, the values by DefsDefs.