class SearchContext (View source)

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.

bool
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

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::class); $list = SiteTree::get();

Parameters

array ...$args

Return Value

Injectable

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

__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

FieldList getSearchFields()

Returns scaffolded search fields for UI.

Return Value

FieldList

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

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

bool clearEmptySearchFields(mixed $value)

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

Parameters

mixed $value

Return Value

bool

SearchFilter getFilter(string $name)

Accessor for the filter attached to a named field.

Parameters

string $name

Return Value

SearchFilter

SearchFilter[] getFilters()

Get the map of filters in the current search context.

Return Value

SearchFilter[]

setFilters(array $filters)

Overwrite the current search context filter map.

Parameters

array $filters

addFilter(SearchFilter $filter)

Adds a instance of {@link SearchFilter}.

Parameters

SearchFilter $filter

removeFilterByName(string $name)

Removes a filter by name.

Parameters

string $name

FieldList getFields()

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

Return Value

FieldList

setFields(FieldList $fields)

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

Parameters

FieldList $fields

addField(FormField $field)

Adds a new {@link FormField} instance.

Parameters

FormField $field

removeFieldByName(string $fieldName)

Removes an existing formfield instance by its name.

Parameters

string $fieldName

$this setSearchParams(array|HTTPRequest $searchParams)

Set search param values

Parameters

array|HTTPRequest $searchParams

Return Value

$this

array getSearchParams()

Return Value

array

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