Sorting
in package
Provides methods to create sorted tables
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
- getFieldArray() : array<string|int, mixed>
- Returns the field array as provided to the constructor
- 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
- getFieldindex() : string
- Extracts table name, field name, and direction from an order definition in SQL syntax and returns them in a string
- getHeaderArray() : array<string|int, mixed>
- Returns an array of strings to display the table headers.
- 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
- getOrderDirectionImage() : string
- Returns an HTML img tag with the icon representing the current order direction
- getOrderDirectionReverse() : string
- Returns the reverse sorting direction string
- getOrderField() : string
- Returns the current order field name
- getOrderParameterName() : string
- Returns the order parameter name used for this Sorting
- getOrderReverseUriEncoded() : string
- Returns the sorting order string in URI encoded format
- getOrderUriEncoded() : string
- Returns the sorting order string in URI encoded format
- getUri_entities() : string
- Returns the base URI with HTML entities encoded
- parseHeaders() : mixed
- Parses all available ordering options into the blocks available
- setOrder() : mixed
- Sets the order string (SQL-ish syntax)
- setOrderDirection() : mixed
- Set the sorting direction string
- setOrderParameterName() : mixed
- Set the order parameter name to be used for this Sorting
- setUri() : mixed
- Sets the base URI
Constants
DEFAULT_PARAMETER_NAME
Default URL parameter name for the sorting order
public
mixed
DEFAULT_PARAMETER_NAME
= 'x_order'
You MUST specify this yourself using setOrderParameterName() when using more than one Sorting at a time!
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.
private
array<string|int, mixed>
$arrField
= \null
Note that the first element will be the default sorting field.
$baseUri
The base page URI to use.
private
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! See setUri().
$flagDefaultAsc
Flag indicating the default order
private
bool
$flagDefaultAsc
= \null
if true, the default order is ascending, or descending otherwise.
$orderDirection
The order direction. See {@link setOrder()}.
private
string
$orderDirection
= \null
$orderField
The order field name. See {@link setOrder()}.
private
string
$orderField
= \null
Note that this may include the table name, and even the order direction!
$orderUriParameter
The order parameter name for this Sorting
private
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
SortinggetFieldArray()
Returns the field array as provided to the constructor
public
getFieldArray() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —The field array
getFieldDirection()
Extracts table plus field name, and the direction from an order definition in SQL syntax and returns them in an array
public
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
getFieldindex()
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
getHeaderArray()
Returns an array of strings to display the table headers.
public
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.
getHeaderForField()
Returns a string to display the table header for the given field name.
public
getHeaderForField(string $field[, string $direction = null ]) : 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 = null
-
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
getOrderDirectionImage()
Returns an HTML img tag with the icon representing the current order direction
public
getOrderDirectionImage() : string
Note that the decision where to include the icon or not must be made by the code calling.
Return values
string —The HTML img tag for the sorting direction icon
getOrderDirectionReverse()
Returns the reverse sorting direction string
public
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
getOrderField()
Returns the current order field name
public
getOrderField() : string
Tags
Return values
string —The field name
getOrderParameterName()
Returns the order parameter name used for this Sorting
public
getOrderParameterName() : string
Tags
Return values
string —The parameter name
getOrderReverseUriEncoded()
Returns the sorting order string in URI encoded format
public
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
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
getUri_entities()
Returns the base URI with HTML entities encoded
public
getUri_entities([string $field = null ]) : string
If the optional $field parameter contains any valid field name, the sorting and direction for that field is appended.
Parameters
- $field : string = null
-
The optional field name
Return values
string —The URI
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
setOrder()
Sets the order string (SQL-ish syntax)
public
setOrder(string $order) : mixed
Parameters
- $order : string
-
The order string
Tags
setOrderDirection()
Set the sorting direction string
public
setOrderDirection([string $direction = 'ASC' ]) : mixed
$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
Tags
setOrderParameterName()
Set the order parameter name to be used for this Sorting
public
setOrderParameterName(string $parameter_name) : mixed
Parameters
- $parameter_name : string
-
The parameter name
Tags
setUri()
Sets the base URI
public
setUri(string $uri) : mixed
Parameters
- $uri : string
-
The URI