\Dewdrop\FieldsOptionGroups

The OptionGroups class makes it easy to retrieve a list of key-value pairs in arrays grouped by a key for use as options for a field's value, typically a foreign key. OptionGroups is ideal for use with a CascadeSelect, for example.

Typically, you'll just need to call setGroupColumn() to get OptionGroups working. If the auto-generated SQL statement isn't doing what you need, you can call setSelect() to provide your own. Just ensure its resultset returns "title", "value" and "group" keys in its rows.

Summary

Methods
Properties
Constants
__construct()
getTableName()
getTitleColumn()
detectTitleColumn()
setOptions()
setTableName()
setValueColumn()
setTitleColumn()
getSelect()
setSelect()
getStmt()
setStmt()
fetch()
fetchJsonWrapper()
setOptionPairs()
setGroupColumn()
No public properties found
No constants found
formatJsonWrapper()
generateStmt()
getSelectColumns()
hasTitleColumn()
findTitleColumnFromMetadata()
findValueColumnFromMetadata()
filterStmt()
orderStmt()
loadTableMetadata()
$dbAdapter
$tableName
$valueColumn
$titleColumn
$stmt
$optionPairs
$groupColumn
N/A
No private methods found
No private properties found
N/A

Properties

$dbAdapter

$dbAdapter : \Dewdrop\Db\Adapter

The database adapter that will be used to retrieve the options.

Type

\Dewdrop\Db\Adapter

$tableName

$tableName : string

The name of the table from which the options will be retrieved.

Type

string

$valueColumn

$valueColumn : string

The name of the column that should be used for the value.

Type

string

$titleColumn

$titleColumn : \Dewdrop\Db\Expr|string

The name of the column that should be used for the option's title.

A \Dewdrop\Db\Expr can also be used for the title column, if you'd like to concatenate multiple columns or format them.

Type

\Dewdrop\Db\Expr|string

$stmt

$stmt : \Dewdrop\Db\Select

The \Dewdrop\Db\Select that will be used to retrieve the options.

Type

\Dewdrop\Db\Select

$optionPairs

$optionPairs : \Dewdrop\Fields\OptionPairs

Present so we can re-use customizations made to the OptionPairs object on a field.

Type

\Dewdrop\Fields\OptionPairs

$groupColumn

$groupColumn : string

The name of the column by which the options should be grouped.

Type

string

Methods

__construct()

__construct(\Dewdrop\Db\Adapter  $dbAdapter) 

Create new OptionPairs object using supplied DB adapter.

Parameters

\Dewdrop\Db\Adapter $dbAdapter

getTableName()

getTableName() : string

Get the table name.

Returns

string

getTitleColumn()

getTitleColumn() : \Dewdrop\Db\Expr|string

Get the title column.

Returns

\Dewdrop\Db\Expr|string

detectTitleColumn()

detectTitleColumn() 

setOptions()

setOptions(array  $options) : \Dewdrop\Fields\OptionPairs

Set one more options on this object. If a setter is not available for the option designated by keys in your options array, an exception will be thrown.

Parameters

array $options

Throws

\Dewdrop\Exception

Returns

\Dewdrop\Fields\OptionPairs

setTableName()

setTableName(string  $tableName) : \Dewdrop\Fields\OptionPairs

Set the name of the table where options can be found.

Parameters

string $tableName

Returns

\Dewdrop\Fields\OptionPairs

setValueColumn()

setValueColumn(string  $valueColumn) : \Dewdrop\Fields\OptionPairs

Set the name of the column that should be used for the value of each option.

Parameters

string $valueColumn

Returns

\Dewdrop\Fields\OptionPairs

setTitleColumn()

setTitleColumn(\Dewdrop\Db\Expr|string  $titleColumn) : \Dewdrop\Fields\OptionPairs

Set the name of the column that should be used for the title of each option. You can also use a \Dewdrop\Db\Expr here, if you'd like to do any special formatting or concatenate multiple columns.

Parameters

\Dewdrop\Db\Expr|string $titleColumn

Returns

\Dewdrop\Fields\OptionPairs

getSelect()

getSelect() : \Dewdrop\Db\Select

An alias for getStmt().

Returns

\Dewdrop\Db\Select

getStmt()

getStmt() : \Dewdrop\Db\Select

Get the \Dewdrop\Db\Select that will be used for retrieving options. If one isn't already available, it will be generated using the other properties on this object. You can call this method to get a good starting point for your SQL and manipulate it from there to apply any specials filters or sorts.

Returns

\Dewdrop\Db\Select

setStmt()

setStmt(\Dewdrop\Db\Select  $stmt) : \Dewdrop\Fields\OptionPairs

Manually set the \Dewdrop\Db\Select that will be used to retrieve options. This can be useful if you'd prefer to skip the default SQL generation logic completely.

Parameters

\Dewdrop\Db\Select $stmt

Returns

\Dewdrop\Fields\OptionPairs

fetch()

fetch() : array

Fetch the option groups using the DB adapter.

Returns

array

fetchJsonWrapper()

fetchJsonWrapper() : array

Wrap the option pairs in such a way that their sort order will be maintained when encoded as JSON. This method doesn't do the JSON encoding itself, just makes it JSON encoding friendly.

Returns an array where each element is another associated array containing "value" and "title" keys.

Returns

array

setOptionPairs()

setOptionPairs(\Dewdrop\Fields\OptionPairs  $optionPairs) : $this

Set an OptionPairs object we can look at to re-use customizations.

Parameters

\Dewdrop\Fields\OptionPairs $optionPairs

Returns

$this

setGroupColumn()

setGroupColumn(  $groupColumn) : $this

Set the column by which options will be grouped.

Parameters

$groupColumn

Returns

$this

formatJsonWrapper()

formatJsonWrapper(array  $options) 

Parameters

array $options

generateStmt()

generateStmt() : \Dewdrop\Db\Select

Generate a \Dewdrop\Db\Select object for retrieving options using the metadata of the option table. Prior to this method being called, at least the $tableName property must be set. We will attempt to guess the value and title columns, if they are not set, but the table is needed to retrieve the other metadata.

Returns

\Dewdrop\Db\Select

getSelectColumns()

getSelectColumns() : array

Ensure we retrieve the group column along with the others generating a SQL statement.

Throws

\Dewdrop\Fields\OptionGroups\GroupColumnNotSetException

Returns

array

hasTitleColumn()

hasTitleColumn() : boolean

Check to see if a title column has been set.

Returns

boolean

findTitleColumnFromMetadata()

findTitleColumnFromMetadata(array  $columns) : string

If no title column has been set on this OptionGroups object directly, we attempt to get it from the OptionPairs object, if present. This allows a user to set a custom title column on OptionPairs and have it automatically take effect on OptionGroups as well. Otherwise, we'll revert back to the standard auto-detection behavior.

Parameters

array $columns

The "columns" portion of the table metadata.

Throws

\Dewdrop\Fields\OptionPairs\TitleColumnNotDetectedException

Returns

string

findValueColumnFromMetadata()

findValueColumnFromMetadata(array  $columns) : string

This method is called if now value column has been set by the time generateStmt() is called. We'll attempt to use the first column from the options table that is part of the primary key. If no primary key column is found (what have you done!?), we'll throw an exception asking the developer to manually specify the value column.

Parameters

array $columns

Throws

\Dewdrop\Exception

Returns

string

filterStmt()

filterStmt(array  $columns, \Dewdrop\Db\Select  $stmt) : \Dewdrop\Db\Select

Attempt to apply some default filters to a generated options statement. Dewdrop supported two similar conventions here: "active" columns and "deleted" columns. If your options table has an "active" column, only options for which "active" is true will be included.

If your options table has a "deleted" column, options with that column set as true will be excluded.

Parameters

array $columns

The columns portion of the table metadata.

\Dewdrop\Db\Select $stmt

Returns

\Dewdrop\Db\Select

orderStmt()

orderStmt(array  $columns, \Dewdrop\Db\Select  $stmt) : \Dewdrop\Db\Select

Attempt to order the options statement using the options table metadata. Dewdrop supports two manual sorting columns by convention: sort_index and sort_order. If either of those columns is present in your options table, the options will be sorted by them. Otherwise, we'll sort by the title column.

Parameters

array $columns

The columns portion of the table metadata.

\Dewdrop\Db\Select $stmt

Returns

\Dewdrop\Db\Select

loadTableMetadata()

loadTableMetadata() : array

Load the metadata for the options table.

Throws

\Dewdrop\Exception

Returns

array