« Back to list view

ullSearch framework

Overview

A graphical overview can be found here: ullSearch.png

 

The ullSearch framework (aka 'advanced search') is responsible for:

  • providing an user interface where search criteria can be added and removed
  • providing functionality to modify an existing (selecting) Doctrine_Query object with the chosen search criteria.

At the moment, the framework supports searches for the following models:

  • ullUser
  • ullFlowDoc
  • ullVentoryItem

Relation search is also supported, e.g. searching for users where the creator workes in a specific department.

 

The framework is split into two parts, roughly congruent to the two functional requirements described above.


The interface component

A search is started by opening the search form, which provides some default (customer configurable) search fields (like department, location, ...) and a dropdown of all searchable fields; it also includes a NOT-checkbox for every field. Related files are ullSearchForm.php and ullSearchAddCriteriaForm.php.


Accordingly, to configure a search form a configuration object, called 'search configuration class', is used.


The class ullSearchConfig is abstract and forces implementing classes to provide two functions:

  • configureDefaultSearchColumns()
  • getAllSearchableColumns()

See the ullUserSearchConfig and ullFlowDocSearchConfig classes for examples.
Note that the search configuration class name for a model is not hardcoded, but configurable in the app.yml file, see ullCorePlugin/config/app.yml.

 

The two methods described above are expected to return an array of ullSearchFormEntry objects, which are light attribute holders describing a searchable field (column name, relation, isVirtual). There is also an attribute called 'multiple count', since the search framework also supports searching the same column more than once, concatenated by logical ORs.

 

On instantiation of a new search the default list of search form entries is copied to the current session; this list gets updated accordingly if the user adds or removes criterions.

 

The class responsible for the actual form-building is called ullSearchGenerator. Although it shares structural similiarities with the Generator framework, it's not derived from ullGenerator but only ullGeneratorBase. The related classes (e.g. ullFlowSearchGenerator) constitute their own class hierarchy.


For the developer the main interaction happens with the following functions:

  • the constructor (which takes an array of search form entries)
  • the getForm() function, which retrieves the built form
  • customColumnConfig(ullColumnConfiguration)

customColumnConfig is intented to be overridden to provide additional functionality like virtual column support.

 

The ullSearchActionHelper class provides additional functions needed for search form event handling (adding and removing criteria). The example implementation shows how these functions should be used, see BaseUllUserActions - function executeSearch() - for reference.

 

The query component

On submit of the search form the second part of the ullSearch framework is activated.


First, the list of search form entries is transformed into a collection of criteria objects. Currently, the following classes exist:

  • ullSearchCompareCriterion - 'a and b' searches for 'a', 'and', 'b', ignoring order, using 'LIKE'
  • ullSearchCompareExactCriterion - 'a and b' searches for 'a and b'
  • ullSearchRangeCriterion - searches for <=, >= or between
  • ullSearchBooleanCriterion - searches for yes or no
  • ullSearchForeignKeyCriterion - searches for exact id matches, using '='

All these classes inherit from the abstract ullSearchCriterion class, which includes 'column name' and 'isNot' attributes. Multiple criterion objects are grouped into a ullSearchCriterionGroup. See ullSearchCriteriaClasses for class definitions.

 

The actual transformation from search form entries to criteria object groups is done by the ullSearchFormEntryHelper.

 

This groups are then forwarded to the ullSearch (respectively ullFlowSearch) class, which is responsible for query object modification, via the

  • modifyQuery

function, which takes a Doctrine_Query object and the name of the alias (e.g. 'x').
Note that the function doesn't check anything about the given query object - it just adds WHERE clauses according to the wrapped ullSearchCriterionGroup objects.

 

For virtual column support the ullFlowSearch class inherits ullSearch and overrides the following functions:

  • modifyColumnName(string name)
  • modifyAlias(Doctrine_Query query, alias, ullSearchCriterion criterion)