class SearchContext

Manages searching of properties on one or more {@link DataObject} types, based on a given set of input parameters.

SearchContext is intentionally decoupled from any controller-logic, it just receives a set of search parameters and an object class it acts on.

The default output of a SearchContext is either a {@link SQLSelect} object for further refinement, or a {@link SS_List} that can be used to display search results, e.g. in a {@link TableListField} instance.

In case you need multiple contexts, consider namespacing your request parameters by using {@link FieldList->namespace()} on the $fields constructor parameter.

Each DataObject subclass can have multiple search contexts for different cases, e.g. for a limited frontend search and a fully featured backend search. By default, you can use {@link DataObject->getDefaultSearchContext()} which is automatically scaffolded. It uses {@link DataObject::$searchable_fields} to determine which fields to include.

Traits

A class that can be instantiated or replaced via DI

Properties

string $connective The logical connective used to join WHERE clauses. Defaults to AND.

Methods

static Injectable
create(array $args)

An implementation of the factory method, allows you to create an instance of a class

static Injectable
singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

__construct(string $modelClass, FieldList $fields = null, array $filters = null)

A key value pair of values that should be searched for.

getSearchFields()

Returns scaffolded search fields for UI.

getQuery(array $searchParams, array|bool|string $sort = false, array|bool|string $limit = false, DataList $existingQuery = null)

Returns a SQL object representing the search context for the given list of query parameters.

getResults(array $searchParams, array|bool|string $sort = false, array|bool|string $limit = false)

Returns a result set from the given search parameters.

boolean
clearEmptySearchFields(mixed $value)

Callback map function to filter fields with empty values from being included in the search expression.

getFilter(string $name)

Accessor for the filter attached to a named field.

getFilters()

Get the map of filters in the current search context.

setFilters(array $filters)

Overwrite the current search context filter map.

addFilter(SearchFilter $filter)

Adds a instance of {@link SearchFilter}.

removeFilterByName(string $name)

Removes a filter by name.

getFields()

Get the list of searchable fields in the current search context.

setFields(FieldList $fields)

Apply a list of searchable fields to the current search context.

addField(FormField $field)

Adds a new {@link FormField} instance.

removeFieldByName(string $fieldName)

Removes an existing formfield instance by its name.

$this
setSearchParams(array|HTTPRequest $searchParams)

Set search param values

array
getSearchParams()

No description

getSummary()

Gets a list of what fields were searched and the values provided for each field. Returns an ArrayList of ArrayData, suitable for rendering on a template.

Details

in Injectable at line 26
static Injectable create(array $args)

An implementation of the factory method, allows you to create an instance of a class

This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.

This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create('SiteTree'); $list = SiteTree::get();

Parameters

array $args

Return Value

Injectable

in Injectable at line 43
static Injectable singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).

Parameters

string $class Optional classname to create, if the called class should not be used

Return Value

Injectable The singleton instance

at line 95
__construct(string $modelClass, FieldList $fields = null, array $filters = null)

A key value pair of values that should be searched for.

The keys should match the field names specified in {@link self::$fields}. Usually these values come from a submitted searchform in the form of a $_REQUEST object. CAUTION: All values should be treated as insecure client input.

Parameters

string $modelClass The base {@link DataObject} class that search properties related to. Also used to generate a set of result objects based on this class.
FieldList $fields Optional. FormFields mapping to {@link DataObject::$db} properties which are to be searched. Derived from modelclass using {@link DataObject::scaffoldSearchFields()} if left blank.
array $filters Optional. Derived from modelclass if left blank

at line 107
FieldList getSearchFields()

Returns scaffolded search fields for UI.

Return Value

FieldList

at line 146
DataList getQuery(array $searchParams, array|bool|string $sort = false, array|bool|string $limit = false, DataList $existingQuery = null)

Returns a SQL object representing the search context for the given list of query parameters.

Parameters

array $searchParams Map of search criteria, mostly taken from $_REQUEST. If a filter is applied to a relationship in dot notation, the parameter name should have the dots replaced with double underscores, for example "Comments__Name" instead of the filter name "Comments.Name".
array|bool|string $sort Database column to sort on. Falls back to {@link DataObject::$default_sort} if not provided.
array|bool|string $limit
DataList $existingQuery

Return Value

DataList

Exceptions

Exception

at line 205
DataList getResults(array $searchParams, array|bool|string $sort = false, array|bool|string $limit = false)

Returns a result set from the given search parameters.

Parameters

array $searchParams
array|bool|string $sort
array|bool|string $limit

Return Value

DataList

Exceptions

Exception

at line 220
boolean clearEmptySearchFields(mixed $value)

Callback map function to filter fields with empty values from being included in the search expression.

Parameters

mixed $value

Return Value

boolean

at line 231
SearchFilter getFilter(string $name)

Accessor for the filter attached to a named field.

Parameters

string $name

Return Value

SearchFilter

at line 245
SearchFilter[] getFilters()

Get the map of filters in the current search context.

Return Value

SearchFilter[]

at line 255
setFilters(array $filters)

Overwrite the current search context filter map.

Parameters

array $filters

at line 265
addFilter(SearchFilter $filter)

Adds a instance of {@link SearchFilter}.

Parameters

SearchFilter $filter

at line 275
removeFilterByName(string $name)

Removes a filter by name.

Parameters

string $name

at line 285
FieldList getFields()

Get the list of searchable fields in the current search context.

Return Value

FieldList

at line 295
setFields(FieldList $fields)

Apply a list of searchable fields to the current search context.

Parameters

FieldList $fields

at line 305
addField(FormField $field)

Adds a new {@link FormField} instance.

Parameters

FormField $field

at line 315
removeFieldByName(string $fieldName)

Removes an existing formfield instance by its name.

Parameters

string $fieldName

at line 326
$this setSearchParams(array|HTTPRequest $searchParams)

Set search param values

Parameters

array|HTTPRequest $searchParams

Return Value

$this

at line 340
array getSearchParams()

Return Value

array

at line 352
ArrayList getSummary()

Gets a list of what fields were searched and the values provided for each field. Returns an ArrayList of ArrayData, suitable for rendering on a template.

Return Value

ArrayList