Editor PHP 2.4.0

Options extends Ext
in package

The Options class provides a convenient method of specifying where Editor should get the list of options for a `select`, `radio` or `checkbox` field.

This is normally from a table that is left joined to the main table being edited, and a list of the values available from the joined table is shown to the end user to let them select from.

Options instances are used with the Field->options() method.

Tags
example

Get a list of options from the sites table

(new Field( 'users.site' ))
    ->options( (new Options())
        ->table( 'sites' )
        ->value( 'id' )
        ->label( 'name' )
    )
example

Get a list of options with custom ordering

(new Field( 'users.site' ))
    ->options( (new Options())
        ->table( 'sites' )
        ->value( 'id' )
        ->label( 'name' )
        ->order( 'name DESC' )
    )
example

Get a list of options showing the id and name in the label

(new Field( 'users.site' ))
    ->options( (new Options())
        ->table( 'sites' )
        ->value( 'id' )
        ->label( [ 'name', 'id' ] )
        ->render( function ( $row ) {
          return $row['name'].' ('.$row['id'].')';
        } )
    )

Table of Contents

Methods

__construct()  : mixed
Constructor.
add()  : $this
Add extra options to the list, in addition to any obtained from the database. Note that these go through the same filtering and ordering operation as database retrieved values (they are merged together if both are used). Use a custom function if you want complete control over the options and their order.
alwaysRefresh()  : mixed
Get / set the flag to indicate if the options should always be refreshed (i.e. on get, create and edit) or only on the initial data load (false).
execDb()  : array<string|int, mixed>
Get the list of options from the database based on the configuration.
find()  : array<string|int, mixed>|bool
Get the objects for a set of values.
fn()  : mixed
Custom function to get the options, rather than using the built in DB.
include()  : mixed
Column names from `value()` and `label()` that should be included in the output object for each option, in addition to the value and label.
inst()  : static
Static method to instantiate a new instance of a class (shorthand of 'instantiate').
instantiate()  : static
Static method to instantiate a new instance of a class.
label()  : mixed
Get / set the column(s) to use as the label value of the options.
leftJoin()  : $this
Set up a left join operation for the options.
limit()  : mixed
Get / set the LIMIT clause to limit the number of records returned.
order()  : mixed
Get / set the ORDER BY clause to use in the SQL. If this option is `true` (which it is by default) the ordering will be based on the rendered output, either numerically or alphabetically based on the data returned by the renderer. If `false` no ordering will be performed and whatever is returned from the database will be used.
render()  : mixed
Get / set the label renderer. The renderer can be used to combine multiple database columns into a single string that is shown as the label to the end user in the list of options.
search()  : array<string|int, mixed>|bool
Do a search for data on the source.
searchOnly()  : mixed
Get / set the search only flag. If enabled the options will only be resolved when doing a search for options on this specific instance.
table()  : mixed
Get / set the database table from which to gather the options for the list.
value()  : mixed
Get / set the column name to use for the value in the options list. This would normally be the primary key for the table.
where()  : mixed
Get / set the method to use for a WHERE condition if it is to be applied to the query to get the options.
_getSet()  : mixed
Common getter / setter function for DataTables classes.
_propExists()  : bool
Determine if a property is available in a data set (allowing `null` to be a valid value).
_readProp()  : mixed
Read a value from a data structure, using Javascript dotted object notation. This is the inverse of the `_writeProp` method and provides the same support, matching DataTables' ability to read nested JSON data objects.
_writeProp()  : mixed
Write the field's value to an array structure, using Javascript dotted object notation to indicate JSON data structure. For example `name.first` gives the data structure: `name: { first: ... }`. This matches DataTables own ability to do this on the client-side, although this doesn't implement implement quite such a complex structure (no array / function support).

Methods

__construct()

Constructor.

public __construct([string|callable $table = null ][, string $value = null ][, string $label = null ]) : mixed
Parameters
$table : string|callable = null

As a string this is the database table name - see ->table(). If given as a function, then it is passed to ->fn() as a custom function.

$value : string = null

The database column name to use as the value for the options - see ->value()

$label : string = null

The database column name to use as the label for the options - see ->label().

add()

Add extra options to the list, in addition to any obtained from the database. Note that these go through the same filtering and ordering operation as database retrieved values (they are merged together if both are used). Use a custom function if you want complete control over the options and their order.

public add(string $label[, string|null $value = null ]) : $this
Parameters
$label : string

The label to use for the option

$value : string|null = null

Value for the option. If not given, the label will be used

Return values
$this

alwaysRefresh()

Get / set the flag to indicate if the options should always be refreshed (i.e. on get, create and edit) or only on the initial data load (false).

public alwaysRefresh([bool|null $_ = null ]) : mixed
Parameters
$_ : bool|null = null

Flag to set the always refresh set to, or null to get the current state.

execDb()

Get the list of options from the database based on the configuration.

public execDb(Database $db, array<string|int, mixed>|false $find) : array<string|int, mixed>
Parameters
$db : Database

Database connection

$find : array<string|int, mixed>|false

Values to search for

Return values
array<string|int, mixed> —

List of data from the db

find()

Get the objects for a set of values.

public find(Database $db, array<string|int, mixed> $ids) : array<string|int, mixed>|bool
Parameters
$db : Database

Database connection

$ids : array<string|int, mixed>

IDs to get

Return values
array<string|int, mixed>|bool

fn()

Custom function to get the options, rather than using the built in DB.

public fn([callable|null $_ = null ]) : mixed
Parameters
$_ : callable|null = null

Function that will be run to get the list of options.

include()

Column names from `value()` and `label()` that should be included in the output object for each option, in addition to the value and label.

public include([string|array<string|int, string> $inc = null ]) : mixed
Parameters
$inc : string|array<string|int, string> = null

The list of columns to include in the output

inst()

Static method to instantiate a new instance of a class (shorthand of 'instantiate').

public static inst() : static

This method performs exactly the same actions as the 'instantiate' static method, but is simply shorter and easier to type!

Return values
static —

class

instantiate()

Static method to instantiate a new instance of a class.

public static instantiate() : static

A factory method that will create a new instance of the class that has extended 'Ext'. This allows classes to be instantiated and then chained - which otherwise isn't available until PHP 5.4. If using PHP 5.4 or later, simply create a 'new' instance of the target class and chain methods as normal.

Return values
static —

Instantiated class

label()

Get / set the column(s) to use as the label value of the options.

public label([string|array<string|int, string>|null $_ = null ]) : mixed
Parameters
$_ : string|array<string|int, string>|null = null

null to get the current value, string or array to get.

leftJoin()

Set up a left join operation for the options.

public leftJoin(string $table, string $field1, string $operator, string $field2) : $this
Parameters
$table : string

to get the information from

$field1 : string

the first field to get the information from

$operator : string

the operation to perform on the two fields

$field2 : string

the second field to get the information from

Return values
$this

limit()

Get / set the LIMIT clause to limit the number of records returned.

public limit([number|null $_ = null ]) : mixed
Parameters
$_ : number|null = null

Number of rows to limit the result to

order()

Get / set the ORDER BY clause to use in the SQL. If this option is `true` (which it is by default) the ordering will be based on the rendered output, either numerically or alphabetically based on the data returned by the renderer. If `false` no ordering will be performed and whatever is returned from the database will be used.

public order([string|bool|null $_ = null ]) : mixed
Parameters
$_ : string|bool|null = null

String to set, null to get current value

render()

Get / set the label renderer. The renderer can be used to combine multiple database columns into a single string that is shown as the label to the end user in the list of options.

public render([callable(array<string|int, mixed>): string|null $_ = null ]) : mixed
Parameters
$_ : callable(array<string|int, mixed>): string|null = null

Function to set, null to get current value

search()

Do a search for data on the source.

public search(Database $db, string $term) : array<string|int, mixed>|bool
Parameters
$db : Database

Database connection

$term : string

Search term

Return values
array<string|int, mixed>|bool

searchOnly()

Get / set the search only flag. If enabled the options will only be resolved when doing a search for options on this specific instance.

public searchOnly([bool|null $_ = null ]) : mixed
Parameters
$_ : bool|null = null

Flag to set the search only set to, or null to get the current state.

table()

Get / set the database table from which to gather the options for the list.

public table([string|null $_ = null ]) : mixed
Parameters
$_ : string|null = null

String to set, null to get current value

value()

Get / set the column name to use for the value in the options list. This would normally be the primary key for the table.

public value([string|null $_ = null ]) : mixed
Parameters
$_ : string|null = null

String to set, null to get current value

where()

Get / set the method to use for a WHERE condition if it is to be applied to the query to get the options.

public where([callable(Query): void|null $_ = null ]) : mixed
Parameters
$_ : callable(Query): void|null = null

Function to set, null to get current value

_getSet()

Common getter / setter function for DataTables classes.

protected _getSet(mixed &$prop, mixed $val[, bool $array = false ]) : mixed

This getter / setter method makes building getter / setting methods easier, by abstracting everything to a single function call.

Parameters
$prop : mixed

The property to set

$val : mixed

The value to set - if given as null, then we assume that the function is being used as a getter.

$array : bool = false

Treat the target property as an array or not (default false). If used as an array, then values passed in are added to the $prop array.

_propExists()

Determine if a property is available in a data set (allowing `null` to be a valid value).

protected _propExists(string $name, array<string|int, mixed> $data) : bool
Parameters
$name : string

Javascript dotted object name to write to

$data : array<string|int, mixed>

Data source array to read from

Return values
bool —

true if present, false otherwise

_readProp()

Read a value from a data structure, using Javascript dotted object notation. This is the inverse of the `_writeProp` method and provides the same support, matching DataTables' ability to read nested JSON data objects.

protected _readProp(string $name, array<string|int, mixed> $data) : mixed
Parameters
$name : string

Javascript dotted object name to write to

$data : array<string|int, mixed>

Data source array to read from

Return values
mixed —

The read value, or null if no value found.

_writeProp()

Write the field's value to an array structure, using Javascript dotted object notation to indicate JSON data structure. For example `name.first` gives the data structure: `name: { first: ... }`. This matches DataTables own ability to do this on the client-side, although this doesn't implement implement quite such a complex structure (no array / function support).

protected _writeProp(array<string|int, mixed> &$out, string $name, mixed $value) : mixed
Parameters
$out : array<string|int, mixed>

Array to write the data to

$name : string

Javascript dotted object name to write to

$value : mixed

Value to write


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results