Applying a default filter on a table

In many scenarios, you may find it useful to apply an initial filter on one or more of your application tables. This is very easy to achieve using the tablename_init hook. The idea is to check whether your table has any filters applied to it, and if none is applied, apply the default filter. This way, your application users will see a pre-filtered list of records, and they can then change the filter(s) later.



Let's first explain briefly how filters work in AppGini. A filter has five parts that fully define it:
  1. The filter index. The first filter has an index of 1, the second filter 2, ... etc.
  2. The index of the field being filtered, as defined in your AppGini project. For example, if you want to filter on the "FirstName" field, which happens to be the fourth field in your table, the field index in this case is 4.
  3. The filter type (operator) to use (equal to, less than, like ... etc.)
  4. The filtered value (the search string)
  5. How to combine the filter with the previous filter (either 'and' or 'or')


As an example, let's assume we have a "customers" table, and we want to apply an initial filter to show customers with a status of "New". Let's assume that the "status" field happens to be the seventh field in the customers table. In the generated "hooks/customers.php" file, find the customers_init hook and change it to read:

	function customers_init(&$options, $memberInfo, &$args){
		/* Apply a default filter only if no filter is already applied by the user */
		if(!$_POST['FilterField'][1] && !$_GET['FilterField'][1]){
			/*
				In the call below, we want to display records of the customers 
				table where the value of the 7th field is equal to 'New'.
			*/
			addFilter(1, 'and', 7, 'equal-to', 'New');
		}
		
		return TRUE;
	}



The addFilter() function used in the above code is used to define a filter. It takes the following arguments:

  1. The filter index.
  2. How to combine with previous filter. Accepted values: 'and', 'or'.
  3. The field index. The first field in a table has an index of 1, the second 2, ... etc.
  4. The filter type (operator). Accepted values (case-sensitive) as of AppGini 5.40 and newer:
    'equal-to', 'not-equal-to', 'greater-than', 'greater-than-or-equal-to', 'less-than', 'less-than-or-equal-to', 'like', 'not-like', 'is-empty', 'is-not-empty'
    • The filter type (operator). Accepted values (case-sensitive) for AppGini 5.31 and older:
      '<=>', '!=', '>', '>=', '<', '<=', 'like', 'not like', 'isEmpty', 'isNotEmpty'
  5. The filterd value.