Sorting
in package
Provides methods to create sorted tables
Use ViewGenerator instead
Tags
Table of Contents
Constants
- DEFAULT_PARAMETER_NAME = 'x_order'
- Default URL parameter name for the sorting order
- REGEX_ORDER_FIELD = '/(?:`?(\w+)`?\.)?`?(\w+)`?(?:\s+(asc|desc))?/i'
- Regular expression used to match the field name and order direction used in an ORDER BY statement
Properties
- $arrField : array<string|int, mixed>
- The array of database field names and header field names.
- $baseUri : string
- The base page URI to use.
- $flagDefaultAsc : bool
- Flag indicating the default order
- $orderDirection : string
- The order direction. See {@link setOrder()}.
- $orderField : string
- The order field name. See {@link setOrder()}.
- $orderUriParameter : mixed
- The order parameter name for this Sorting
Methods
- __construct() : Sorting
- Constructor
- getFieldindex() : string
- Extracts table name, field name, and direction from an order definition in SQL syntax and returns them in a string
- getHeaderForField() : string
- Returns a string to display the table header for the given field name.
- getOrder() : string
- Returns the current order string (SQL-ish syntax)
- getOrderDirection() : string
- Returns the sorting direction string
- getOrderField() : string
- Returns the current order field name
- getOrderFieldClasses() : string
- Returns "asc", "desc" or empty string. In backend "sortable" is returned as well.
- getOrderParameterName() : string
- Returns the order parameter name used for this Sorting
- getOrderUriEncoded() : string
- Returns the sorting order string in URI encoded format
- parseHeaders() : mixed
- Parses all available ordering options into the blocks available
- getFieldDirection() : array<string|int, mixed>
- Extracts table plus field name, and the direction from an order definition in SQL syntax and returns them in an array
- getHeaderArray() : array<string|int, mixed>
- Returns an array of strings to display the table headers.
- getOrderDirectionReverse() : string
- Returns the reverse sorting direction string
- getOrderReverseUriEncoded() : string
- Returns the sorting order string in URI encoded format
- setOrder() : mixed
- Sets the order string (SQL-ish syntax)
- setOrderDirection() : void
- Set the sorting direction string
Constants
DEFAULT_PARAMETER_NAME
Default URL parameter name for the sorting order
public
mixed
DEFAULT_PARAMETER_NAME
= 'x_order'
REGEX_ORDER_FIELD
Regular expression used to match the field name and order direction used in an ORDER BY statement
public
mixed
REGEX_ORDER_FIELD
= '/(?:`?(\w+)`?\.)?`?(\w+)`?(?:\s+(asc|desc))?/i'
Matches the table name ($1), field name ($2), and direction ($3). Ignores leading and trailing "stuff".
Properties
$arrField
The array of database field names and header field names.
protected
array<string|int, mixed>
$arrField
= \null
Note that the first element will be the default sorting field.
$baseUri
The base page URI to use.
protected
string
$baseUri
= \null
The sorting parameters will be appended to this string and used to build the header array. Note that, as this is only used in links, the URI is stored with any "&"s replaced by "&" already!
$flagDefaultAsc
Flag indicating the default order
protected
bool
$flagDefaultAsc
= \null
if true, the default order is ascending, or descending otherwise.
$orderDirection
The order direction. See {@link setOrder()}.
protected
string
$orderDirection
= \null
$orderField
The order field name. See {@link setOrder()}.
protected
string
$orderField
= \null
Note that this may include the table name, and even the order direction!
$orderUriParameter
The order parameter name for this Sorting
protected
mixed
$orderUriParameter
= \null
Methods
__construct()
Constructor
public
__construct(mixed &$baseUri, array<string|int, mixed> $arrField[, bool $flagDefaultAsc = true ][, string $orderUriParameter = self::DEFAULT_PARAMETER_NAME ][, string $defaultOrder = null ]) : Sorting
Note that the base page URI is handed over by reference and that the order parameter name is removed from that, if present.
Parameters
- $baseUri : mixed
- $arrField : array<string|int, mixed>
-
The field names and corresponding header texts
- $flagDefaultAsc : bool = true
-
The flag indicating the default order direction. Defaults to true (ascending).
- $orderUriParameter : string = self::DEFAULT_PARAMETER_NAME
-
The optional name for the URL parameter. Defaults to self::DEFAULT_PARAMETER_NAME
- $defaultOrder : string = null
-
The optional default order. Applies only when none is set in the session already, and if it's a valid field index.
Tags
Return values
SortinggetFieldindex()
Extracts table name, field name, and direction from an order definition in SQL syntax and returns them in a string
public
static getFieldindex(string $order_sql) : string
The string is solely intended for use as an index of the object's field array. It has the form "[table.]field[ direction] Note that if the table name is not found, it is omitted in the respective array element. No dot is included in this case. Similarly, if the direction cannot be extracted from the string, no space is added either.
Parameters
- $order_sql : string
-
The order in SQL syntax
Return values
string —The field array index on success, null otherwise
getHeaderForField()
Returns a string to display the table header for the given field name.
public
getHeaderForField(string $field[, string $direction = '' ]) : string
Uses the order currently stored in the object, as set by setOrder(). The optional $direction overrides the current state of the order direction.
Parameters
- $field : string
-
The field name
- $direction : string = ''
-
The optional direction
Tags
Return values
string —The string for a clickable table header field.
getOrder()
Returns the current order string (SQL-ish syntax)
public
getOrder() : string
Note that this adds backticks around the order table (if present)
and field name. The string looks like
"table.field dir"
or
"field dir"
Tags
Return values
stringgetOrderDirection()
Returns the sorting direction string
public
getOrderDirection() : string
This is either 'ASC' or 'DESC'.
Tags
Return values
string —order direction string
getOrderField()
Returns the current order field name
public
getOrderField() : string
Tags
Return values
string —The field name
getOrderFieldClasses()
Returns "asc", "desc" or empty string. In backend "sortable" is returned as well.
public
getOrderFieldClasses(string $fieldname) : string
This method is inteded to set classes on stuff like
Parameters
- $fieldname : string
-
Name of the field
Return values
string —Classes to set for the field
getOrderParameterName()
Returns the order parameter name used for this Sorting
public
getOrderParameterName() : string
Tags
Return values
string —The parameter name
getOrderUriEncoded()
Returns the sorting order string in URI encoded format
public
getOrderUriEncoded([string $field = '' ]) : string
The returned string contains both the parameter name, and the current order string value.
Parameters
- $field : string = ''
-
The optional order field
Tags
Return values
string —URI encoded order string
parseHeaders()
Parses all available ordering options into the blocks available
public
parseHeaders(Sigma $template, string $blockBase) : mixed
Lower case $blockBase is the base for all template block names. The UPPERCASE version of $blockBase is the name of the (only) placeholder.
Examples for $blockBase = 'shop_product_order':
Standard sorting headers, alternating between ascending and descending. Includes all available criteria. The block name is shop_product_order, the placeholder SHOP_PRODUCT_ORDER.
Custom sorting headers, fixed or alternating
Column and functionality are determined by the block name:
"shop_product_order_" + field name [ + "_" + optional fixed direction ]
Note that non-letter characters in the field name (index) are replaced
by underscores, e.g. an order field declaration of "product.ord"
is stripped of the backticks by getFieldIndex(), resulting in
"product.ord" stored in the field array, then substituted by
"product_ord" in this method.
Note that invalid field names (not matching REGEX_ORDER_FIELD), as well as empty string names (labels) are skipped.
Parameters
- $template : Sigma
-
The Template
- $blockBase : string
-
The block base name
getFieldDirection()
Extracts table plus field name, and the direction from an order definition in SQL syntax and returns them in an array
protected
static getFieldDirection(string $order_sql) : array<string|int, mixed>
The array looks like
array(
0 => [table.]field,
1 => direction,
)
Note that if the table name is not found, it is omitted in the
respective array element. No dot is included in this case.
The direction may be missing, in which case element #1 is set
to the empty string.
Parameters
- $order_sql : string
-
The order in SQL syntax
Return values
array<string|int, mixed> —The array with table plus field name and direction on success, null otherwise
getHeaderArray()
Returns an array of strings to display the table headers.
protected
getHeaderArray() : array<string|int, mixed>
Uses the order currently stored in the object, as set by setOrder(). The array is, of course, in the same order as the arrays of field and header names used.
Tags
Return values
array<string|int, mixed> —The array of clickable table headers.
getOrderDirectionReverse()
Returns the reverse sorting direction string
protected
getOrderDirectionReverse([string $direction = null ]) : string
This is either 'ASC' or 'DESC'. If empty, the $direction parameter defaults to this objects' $orderDirection variable.
Parameters
- $direction : string = null
-
The optional order direction
Tags
Return values
string —The reverse order direction
getOrderReverseUriEncoded()
Returns the sorting order string in URI encoded format
protected
getOrderReverseUriEncoded([mixed $field = '' ]) : string
The returned string contains both the parameter name, 'order', and the current order string value. It is ready to be used in an URI in a link.
Parameters
- $field : mixed = ''
Tags
Return values
string —URI encoded order string
setOrder()
Sets the order string (SQL-ish syntax)
protected
setOrder(string $order) : mixed
Parameters
- $order : string
-
The order string
Tags
setOrderDirection()
Set the sorting direction string
protected
setOrderDirection([string $direction = 'ASC' ]) : void
$direction defaults to 'ASC' and may be left empty, or set to 'ASC' or 'DESC'. Any other value is ignored and the default used instead.
Parameters
- $direction : string = 'ASC'
-
The optional order direction string