\Dewdrop\Fields\HelperSelectSort

This helper allow you to sort a \Dewdrop\Db\Select object by leveraging the Field API. In the case of database-related fields, this helper will auto-detect the data type and other information from the DB schema to determine a reasonable default approach for sorting. For other fields, you will have to specify a custom sort callback.

When defining a custom callback for this helper, use the following callback parameters:

$myField->assignHelperCallback(
    'SelectSort',
    function ($helper, Select $select, $direction) {
        return $select->order("a.my_field {$direction}");
    }
);

Note that $direction is guaranteed by the helper to be "ASC" or "DESC", so you don't need to check that yourself. Your callback does have to return the Select object once it has added the order class. If you do not return the Select, an exception will be thrown.

Also note that in the example the field is specified as "a.my_field" in the ORDER BY clause. If your callback is likely to used against a range of queries, in which the table aliases may vary, you may want to use \Dewdrop\Db\Select's quoteWithAlias() method.

Summary

Methods
Properties
Constants
matchesName()
assign()
getFieldAssignment()
hasValidName()
detectCallableForField()
__construct()
setRequest()
setPrefix()
getPrefix()
setDefaultField()
setDefaultDirection()
modifySelect()
isSorted()
getSortedField()
getSortedDirection()
sortDbDate()
sortDbDefault()
sortDbReference()
No public properties found
No constants found
wrapCallable()
$name
N/A
No private methods found
$assignments
$sortedField
$sortedDirection
$defaultField
$defaultDirection
$request
$prefix
N/A

Properties

$name

$name : string

The name for this helper, used when you want to define a global custom callback for a given field

Type

string

$assignments

$assignments : array

Any per-instance callback assignments for this helper. This array will have field IDs as the keys and callables as the values.

Type

array

$sortedDirection

$sortedDirection : string

The direction we're sorting by currently (either ASC or DESC).

Type

string

$defaultDirection

$defaultDirection : string

The default direction (either ASC or DESC) by which we'll sort.

Type

string

$request

$request : \Dewdrop\Request

The HTTP request where we'll check the query string to see which column is sorted and in which direction.

Type

\Dewdrop\Request

$prefix

$prefix : string

A prefix that can be used with HTTP params if you have multiple sortable listings on a single page and need to prevent them from colliding with one another's parameters.

Type

string

Methods

matchesName()

matchesName(string  $name) : boolean

Check to see if the supplied input matches this helper's name (case-insensitive).

Parameters

string $name

Returns

boolean

assign()

assign(mixed  $assignments, callable  $callable = null) : \Dewdrop\Fields\Helper\HelperAbstract

Assign one more custom per-instance callbacks for this helper. If the $arguments param is an array, this method expects that the keys will be field IDs and the values will be callables, assigning custom callbacks for multiple fields in one call. If, however, $assignments is a string or a FieldInterface object, a single custom callback assignment will be made.

Parameters

mixed $assignments
callable $callable

Returns

\Dewdrop\Fields\Helper\HelperAbstract

getFieldAssignment()

getFieldAssignment(\Dewdrop\Fields\FieldInterface  $field) : callable

Get the callback that will be used for the given FieldInterface object.

Parameters

\Dewdrop\Fields\FieldInterface $field

Throws

\Dewdrop\Fields\Exception\HelperCallableNotAvailableForField

Returns

callable

hasValidName()

hasValidName() : boolean

Ensure the helper has a valid $name value. If not, throw an exception.

All helpers must have a name defined so that global custom callbacks can be added to fields.

Throws

\Dewdrop\Fields\Exception\HelperMustHaveName

Returns

boolean

detectCallableForField()

detectCallableForField(\Dewdrop\Fields\FieldInterface  $field) : false|callable

Try to detect a default callback for the provided field. THis helper will only provide a default for database fields of common types. For custom fields, you'll have to assign your own callback, if you want them to be sortable.

If no callback candidate is found, just return false from this method, which will be detected by getFieldAssignment(), causing execution to halt.

Parameters

\Dewdrop\Fields\FieldInterface $field

Returns

false|callable

__construct()

__construct(\Dewdrop\Request  $request) 

Provide the HTTP request that can be used to detect sorting selections.

Parameters

\Dewdrop\Request $request

setPrefix()

setPrefix(string  $prefix) : $this

Set the HTTP param prefix that can be used to prevent collisions when multiple sortable listings are rendered on a single page.

Parameters

string $prefix

Returns

$this

getPrefix()

getPrefix() : string

Get the HTTP param prefix that can be used to prevent collisions when multiple sortable listings are rendered on a single page.

Returns

string

setDefaultField()

setDefaultField(\Dewdrop\Fields\FieldInterface  $defaultField) : $this

Set the field we should sort on by default.

Parameters

\Dewdrop\Fields\FieldInterface $defaultField

Returns

$this

setDefaultDirection()

setDefaultDirection(string  $defaultDirection) : \Dewdrop\Fields\Helper\SelectSort

Set the default direction that should be used when sorting.

Parameters

string $defaultDirection

Throws

\Dewdrop\Fields\Exception

Returns

\Dewdrop\Fields\Helper\SelectSort

modifySelect()

modifySelect(\Dewdrop\Fields  $fields, \Dewdrop\Db\Select  $select) : \Dewdrop\Db\Select

Given the supplied $fields and \Dewdrop\Request object, find the field referenced in the query string and apply its sort callback to the query.

Parameters

\Dewdrop\Fields $fields
\Dewdrop\Db\Select $select

Throws

\Dewdrop\Fields\Exception

Returns

\Dewdrop\Db\Select

isSorted()

isSorted() : boolean

Check to see if this helper has sorted the Select by a field.

Returns

boolean

getSortedField()

getSortedField() : \Dewdrop\Fields\FieldInterface

Get the field the Select is currently sorted by.

Returns

\Dewdrop\Fields\FieldInterface

getSortedDirection()

getSortedDirection() : string

Get the direction the Select is currently sorted.

Returns

string

sortDbDate()

sortDbDate(\Dewdrop\Db\Field  $field, \Dewdrop\Db\Select  $select, string  $direction) : \Dewdrop\Db\Select

A default implementation for database DATE fields.

Parameters

\Dewdrop\Db\Field $field
\Dewdrop\Db\Select $select
string $direction

Returns

\Dewdrop\Db\Select

sortDbDefault()

sortDbDefault(\Dewdrop\Db\Field  $field, \Dewdrop\Db\Select  $select, string  $direction) : \Dewdrop\Db\Select

A default implementation for most database fields.

Parameters

\Dewdrop\Db\Field $field
\Dewdrop\Db\Select $select
string $direction

Returns

\Dewdrop\Db\Select

sortDbReference()

sortDbReference(\Dewdrop\Db\Field  $field, \Dewdrop\Db\Select  $select, string  $direction) : \Dewdrop\Db\Select

Provide a default sorting strategy for reference columns.

Parameters

\Dewdrop\Db\Field $field
\Dewdrop\Db\Select $select
string $direction

Throws

\Dewdrop\Db\Select\SelectException

Returns

\Dewdrop\Db\Select

wrapCallable()

wrapCallable(callable  $callable, \Dewdrop\Fields\FieldInterface  $field = null) : callable

Wrap a field's callback to ensure that a reference to the helper is always supplied as the first argument to the callback.

Parameters

callable $callable
\Dewdrop\Fields\FieldInterface $field

Returns

callable