Lists
extends WidgetBase
in package
Uses
PreferenceMaker
List Widget Used for building back end lists, renders a list of model objects
Tags
Table of Contents
- $alias : string
- $assetPath : string
- $columns : array<string|int, mixed>
- $config : object
- $cssClasses : array<string|int, mixed>
- $customViewPath : string
- $defaultSort : mixed
- $implement : array<string|int, mixed>
- $layout : string
- $model : Model
- $noRecordsMessage : string
- $recordOnClick : string
- $recordsPerPage : int
- $recordUrl : string
- $showCheckboxes : bool
- $showPageNumbers : bool
- $showPagination : bool|string
- $showSetup : bool
- $showSorting : bool
- $showTree : bool
- $suppressLayout : bool
- $treeExpanded : bool
- $vars : array<string|int, mixed>
- $allColumns : array<string|int, mixed>
- $assets : array<string|int, mixed>
- $columnOverride : array<string|int, mixed>
- $configPath : string
- $controller : Controller
- $currentPageNumber : int
- $defaultAlias : string
- $extendableCallbacks : array<string|int, mixed>
- $extendableGuardProperties : bool
- $extendableStaticMethods : array<string|int, mixed>
- $extensionData : array<string|int, mixed>
- $fatalError : string
- $filterCallbacks : array<string|int, mixed>
- $layoutPath : string
- $preferenceCache : array<string|int, mixed>
- Cache for retrieved user preferences.
- $records : array<string|int, mixed>
- $searchMode : string
- $searchScope : string
- $searchTerm : string
- $sortableColumns : array<string|int, mixed>
- $sortColumn : string
- $sortDirection : string
- $viewPath : string|array<string|int, mixed>
- $visibleColumns : array<string|int, mixed>
- __call() : mixed
- __callStatic() : mixed
- __construct() : mixed
- Constructor
- __get() : mixed
- __set() : mixed
- addColumns() : mixed
- Programatically add columns, used internally and for extensibility.
- addCss() : void
- Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
- addDynamicMethod() : mixed
- Programmatically adds a method to the extendable class
- addDynamicProperty() : mixed
- Programmatically adds a property to the extendable class
- addFilter() : mixed
- addJs() : void
- Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
- addRss() : void
- Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
- addViewPath() : void
- Prepends a path on the available view path locations.
- asExtension() : mixed
- Short hand for `getClassExtension()` method, except takes the short extension name, example:
- bindToController() : void
- Binds a widget to the controller for safe use.
- clearExtendedClasses() : void
- Clear the list of extended classes so they will be re-extended.
- clearUserPreference() : void
- Clears a single preference key from the user preferences for this controller/widget.
- clearUserPreferences() : void
- Clears all user preferences for this controller/widget.
- combineAssets() : string
- Run the provided assets through the Asset Combiner
- extend() : mixed
- extendableCall() : mixed
- Magic method for `__call()`
- extendableCallStatic() : mixed
- Magic method for `__callStatic()`
- extendableConstruct() : mixed
- This method should be called as part of the constructor.
- extendableExtendCallback() : void
- Helper method for `::extend()` static method
- extendableGet() : string
- Magic method for `__get()`
- extendableSet() : string
- Magic method for `__set()`
- extendClassWith() : void
- Dynamically extend a class with a specified behavior
- fireSystemEvent() : mixed
- Fires a combination of local and global events. The first segment is removed from the event name locally and the local object is passed as the first argument to the event globally. Halting is also enabled by default.
- fireViewEvent() : string
- Special event function used for extending within view files, allowing HTML to be injected multiple times.
- flushAssets() : void
- Disables the use, and subequent broadcast, of assets. This is useful to call during an AJAX request to speed things up. This method works by specifically targeting the hasAssetsDefined method.
- getAssetPath() : string
- Locates a file based on it's definition. If the file starts with a forward slash, it will be returned in context of the application public path, otherwise it will be returned in context of the asset path.
- getAssetPaths() : array<string|int, mixed>
- Returns an array of all registered asset paths.
- getClassExtension() : mixed
- Returns a behavior object from an extendable class, example:
- getClassMethods() : array<string|int, mixed>
- Get a list of class methods, extension equivalent of get_class_methods()
- getColumn() : mixed
- Get a specified column object
- getColumns() : array<string|int, mixed>
- Get all the registered columns for the instance.
- getColumnValue() : string
- Returns a column value, with filters applied
- getColumnValueRaw() : string
- Returns a raw column value
- getConfig() : string
- Safe accessor for configuration values.
- getConfigPath() : string
- Locates a file based on it's definition. If the file starts with the ~ symbol it will be returned in context of the application base path, otherwise it will be returned in context of the config path.
- getController() : mixed
- Returns the controller using this widget.
- getDynamicProperties() : array<string|int, mixed>
- Returns all dynamic properties and their values
- getEventHandler() : string
- Returns a fully qualified event handler name for this widget.
- getFatalError() : string
- getHeaderValue() : mixed
- Looks up the column header
- getId() : string
- Returns a unique ID for this widget. Useful in creating HTML markup.
- getRecordOnClick() : string
- Returns the onclick event for a list row.
- getRecordUrl() : string
- Returns the record URL address for a list row.
- getRowClass() : string
- Adds a custom CSS class string to a record row
- getSortColumn() : mixed
- Returns the current sorting column, saved in a session or cached.
- getSortDirection() : mixed
- getUserPreference() : mixed
- Retrieves a widget related key/value pair from the user preferences
- getUserPreferences() : array<string|int, mixed>
- Retrieves and caches all user preferences for this particular controller/widget.
- getViewPath() : string
- Locates a file based on its definition. The file name can be prefixed with a symbol (~|$) to return in context of the application or plugin base path, otherwise it will be returned in context of this object view path.
- getViewPaths() : array<string|int, mixed>
- Returns the active view path locations.
- getVisibleColumns() : mixed
- Returns the list columns that are visible by list settings or default
- guessConfigPath() : string
- Guess the package path for the called class.
- guessConfigPathFrom() : string
- Guess the package path from a specified class.
- guessViewPath() : string
- Guess the package path for the called class.
- guessViewPathFrom() : string
- Guess the package path from a specified class.
- handleError() : mixed
- Sets standard page variables in the case of a controller error.
- hasAssetsDefined() : bool
- Returns true if assets any have been added.
- hasFatalError() : bool
- init() : void
- Initialize the widget, called by the constructor and free from its parameters.
- isClassExtendedWith() : bool
- Check if extendable class is extended with a behavior object
- isTreeNodeExpanded() : bool
- Checks if a node (model) is expanded in the session.
- makeAssets() : string
- Outputs `<link>` and `<script>` tags to load assets previously added with addJs and addCss method calls
- makeConfig() : array<string|int, mixed>|stdClass
- Reads the contents of the supplied file and applies it to this object.
- makeConfigFromArray() : stdClass
- Makes a config object from an array, making the first level keys properties of a new object.
- makeFileContents() : string
- Includes a file path using output buffering.
- makeFormWidget() : FormWidgetBase
- Makes a form widget object with the supplied form field and widget configuration.
- makeLayout() : mixed
- Render a layout.
- makeLayoutPartial() : string
- Renders a layout partial
- makePartial() : mixed
- Render a partial file contents located in the views folder.
- makeView() : string
- Loads a view with the name specified. Applies layout if its name is provided by the parent object.
- makeViewContent() : string
- Renders supplied contents inside a layout.
- makeWidget() : mixed|WidgetBase
- Makes a widget object with the supplied configuration file.
- mergeConfig() : stdClass
- Merges two configuration sources, either prepared or not, and returns them as a single configuration object.
- methodExists() : bool
- Checks if a method exists, extension equivalent of method_exists()
- onApplySetup() : mixed
- Event handler to apply the list set up.
- onFilter() : mixed
- Event handler for changing the filter
- onLoadSetup() : mixed
- Event handler to display the list set up.
- onPaginate() : mixed
- Event handler for switching the page number.
- onRefresh() : mixed
- Event handler for refreshing the list.
- onResetSetup() : mixed
- Event handler to apply the list set up.
- onSort() : mixed
- Event handler for sorting the list.
- onToggleTreeNode() : string
- Sets a node (model) to an expanded or collapsed state, stored in the session, then renders the list again.
- prepareModel() : mixed
- prepareQuery() : mixed
- Applies any filters to the model.
- prepareVars() : mixed
- Prepares the list data
- propertyExists() : bool
- Checks if a property exists, extension equivalent of `property_exists()`
- putUserPreference() : void
- Saves a widget related key/value pair in to the users preferences
- removeColumn() : mixed
- Programatically remove a column, used for extensibility.
- render() : string
- Renders the widget.
- resetSession() : void
- Resets all session data related to this widget.
- setSearchOptions() : mixed
- Applies a search options to the list search.
- setSearchTerm() : mixed
- Applies a search term to the list results, searching will disable tree view if a value is supplied.
- validateTree() : void
- Validates the model and settings if showTree is used
- addAsset() : mixed
- Adds the provided asset to the internal asset collections
- applySearchToQuery() : mixed
- Applies the search constraint to a query.
- defineListColumns() : mixed
- Builds an array of list columns with keys as the column name and values as a ListColumn object.
- evalColorPickerTypeValue() : mixed
- Process as background color, to be seen at list
- evalCustomListType() : mixed
- Process a custom list types registered by plugins.
- evalDatetimeTypeValue() : mixed
- Process as a datetime value
- evalDateTypeValue() : mixed
- Process as a date value
- evalNumberTypeValue() : string
- Process as number, proxy to text
- evalPartialTypeValue() : mixed
- Process as partial reference
- evalSwitchTypeValue() : mixed
- Process as boolean switch
- evalTextTypeValue() : string
- Process as text, escape the value
- evalTimesinceTypeValue() : mixed
- Process as diff for humans (1 min ago)
- evalTimetenseTypeValue() : mixed
- Process as time as current tense (Today at 0:00)
- evalTimeTypeValue() : mixed
- Process as a time value
- extendableIsAccessible() : bool
- Checks if a property is accessible, property equivalent of `is_callable()`
- extensionExtractMethods() : void
- Extracts the available methods from a behavior and adds it to the list of callable methods.
- fillFromConfig() : void
- Transfers config values stored inside the $config property directly on to the root object properties. If no properties are defined all config will be transferred if it finds a matching property.
- getAssetEntryBuildPath() : string
- Internal helper, attaches a build code to an asset path
- getAssetScheme() : string
- Internal helper, get asset scheme
- getCurrentPageNumber() : int
- Returns the current page number for the list.
- getLocalPath() : mixed
- getPreferenceKey() : string
- Returns a unique identifier for this widget and controller action for preference storage.
- getPreferenceStorage() : Model
- Specifies the model used for storing the user preferences.
- getRecords() : Collection
- Returns all the records from the supplied model, after filtering.
- getSearchableColumns() : array<string|int, mixed>
- Returns a collection of columns which can be searched.
- getSession() : string
- Retrieves a widget related key/value pair from session data.
- getSetupListColumns() : mixed
- Returns all the list columns used for list set up.
- getSetupPerPageOptions() : mixed
- Returns an array of allowable records per page.
- getSortableColumns() : mixed
- Returns a collection of columns which are sortable.
- getTotalColumns() : mixed
- Calculates the total columns used in the list, including checkboxes and other additions.
- handleViewException() : void
- Handle a view exception.
- isColumnPivot() : bool
- Checks if a column refers to a pivot model specifically.
- isColumnRelated() : bool
- Check if column refers to a relation of the model
- isSortable() : mixed
- Returns true if the column can be sorted.
- loadAssets() : void
- Adds widget specific asset files. Use $this->addJs() and $this->addCss() to register new assets to include on the page.
- makeListColumn() : mixed
- Creates a list column object from it's name and configuration.
- makeSessionId() : string
- Returns a unique session identifier for this widget and controller action.
- parseTableName() : string
- Replaces the @ symbol with a table name in a model
- putSession() : void
- Saves a widget related key/value pair in to session data.
- removeDuplicates() : void
- Removes duplicate assets from the entire collection.
- validateDateTimeValue() : mixed
- Validates a column type as a date
- validateModel() : void
- Validate the supplied form model.
Properties
$alias
public
string
$alias
Defined alias used for this widget.
$assetPath
public
string
$assetPath
Specifies a path to the asset directory.
$columns
public
array<string|int, mixed>
$columns
List column configuration.
$config
public
object
$config
Supplied configuration.
$cssClasses
public
array<string|int, mixed>
$cssClasses
= []
List of CSS classes to apply to the list container element
$customViewPath
public
string
$customViewPath
Specify a custom view path to override partials used by the list.
$defaultSort
public
mixed
$defaultSort
A default sort column to look for.
$implement
public
array<string|int, mixed>
$implement
Extensions implemented by this class.
$layout
public
string
$layout
Layout to use for the view.
$model
public
Model
$model
List model object.
$noRecordsMessage
public
string
$noRecordsMessage
= 'backend::lang.list.no_records'
Message to display when there are no records in the list.
$recordOnClick
public
string
$recordOnClick
Click event for each record row. Replace :id with the record id.
$recordsPerPage
public
int
$recordsPerPage
Maximum rows to display for each page.
$recordUrl
public
string
$recordUrl
Link for each record row. Replace :id with the record id.
$showCheckboxes
public
bool
$showCheckboxes
= false
Display a checkbox next to each record row.
$showPageNumbers
public
bool
$showPageNumbers
= true
Display page numbers with pagination, disable to improve performance.
$showPagination
public
bool|string
$showPagination
= 'auto'
Display pagination when limiting records per page.
$showSetup
public
bool
$showSetup
= false
Display the list set up used for column visibility and ordering.
$showSorting
public
bool
$showSorting
= true
Shows the sorting options for each column.
$showTree
public
bool
$showTree
= false
Display parent/child relationships in the list.
$suppressLayout
public
bool
$suppressLayout
= false
Prevents the use of a layout.
$treeExpanded
public
bool
$treeExpanded
= false
Expand the tree nodes by default.
$vars
public
array<string|int, mixed>
$vars
= []
A list of variables to pass to the page.
$allColumns
protected
array<string|int, mixed>
$allColumns
Collection of all list columns used in this list.
Tags
$assets
protected
array<string|int, mixed>
$assets
= ['js' => [], 'css' => [], 'rss' => []]
Collection of assets to display in the layout.
$columnOverride
protected
array<string|int, mixed>
$columnOverride
Override default columns with supplied key names.
$configPath
protected
string
$configPath
Specifies a path to the config directory.
$controller
protected
Controller
$controller
Backend controller object.
$currentPageNumber
protected
int
$currentPageNumber
Current page number.
$defaultAlias
protected
string
$defaultAlias
= 'list'
A unique alias to identify this widget.
Tags
$extendableCallbacks
protected
static array<string|int, mixed>
$extendableCallbacks
= []
Used to extend the constructor of an extendable class. Eg:
Class::extend(function($obj) { })
$extendableGuardProperties
protected
static bool
$extendableGuardProperties
= true
Indicates if dynamic properties can be created.
$extendableStaticMethods
protected
static array<string|int, mixed>
$extendableStaticMethods
= []
Collection of static methods used by behaviors.
$extensionData
protected
array<string|int, mixed>
$extensionData
= ['extensions' => [], 'methods' => [], 'dynamicMethods' => [], 'dynamicProperties' => []]
Class reflection information, including behaviors.
$fatalError
protected
string
$fatalError
Object used for storing a fatal error.
$filterCallbacks
protected
array<string|int, mixed>
$filterCallbacks
= []
Collection of functions to apply to each list query.
$layoutPath
protected
string
$layoutPath
Specifies a path to the layout directory.
$preferenceCache
Cache for retrieved user preferences.
protected
static array<string|int, mixed>
$preferenceCache
= []
$records
protected
array<string|int, mixed>
$records
Model data collection.
$searchMode
protected
string
$searchMode
If searching the records, specifies a policy to use.
- all: result must contain all words
- any: result can contain any word
- exact: result must contain the exact phrase
$searchScope
protected
string
$searchScope
Use a custom scope method for performing searches.
$searchTerm
protected
string
$searchTerm
Filter the records by a search term.
$sortableColumns
protected
array<string|int, mixed>
$sortableColumns
All sortable columns.
$sortColumn
protected
string
$sortColumn
Sets the list sorting column.
$sortDirection
protected
string
$sortDirection
Sets the list sorting direction (asc, desc)
$viewPath
protected
string|array<string|int, mixed>
$viewPath
Specifies a path to the views directory.
$visibleColumns
protected
array<string|int, mixed>
$visibleColumns
Columns to display and their order.
Methods
__call()
public
__call(mixed $name, mixed $params) : mixed
Parameters
- $name : mixed
- $params : mixed
Return values
mixed —__callStatic()
public
static __callStatic(mixed $name, mixed $params) : mixed
Parameters
- $name : mixed
- $params : mixed
Return values
mixed —__construct()
Constructor
public
__construct() : mixed
Return values
mixed —__get()
public
__get(mixed $name) : mixed
Parameters
- $name : mixed
Return values
mixed —__set()
public
__set(mixed $name, mixed $value) : mixed
Parameters
- $name : mixed
- $value : mixed
Return values
mixed —addColumns()
Programatically add columns, used internally and for extensibility.
public
addColumns(array<string|int, mixed> $columns) : mixed
Parameters
- $columns : array<string|int, mixed>
-
Column definitions
Return values
mixed —addCss()
Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
public
addCss(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
- $name : string
-
Specifies a path (URL) to the script.
- $attributes : array<string|int, mixed> = []
-
Adds extra HTML attributes to the asset link.
Return values
void —addDynamicMethod()
Programmatically adds a method to the extendable class
public
addDynamicMethod(string $dynamicName, callable $method[, string $extension = null ]) : mixed
Parameters
- $dynamicName : string
- $method : callable
- $extension : string = null
Return values
mixed —addDynamicProperty()
Programmatically adds a property to the extendable class
public
addDynamicProperty(string $dynamicName[, string $value = null ]) : mixed
Parameters
- $dynamicName : string
- $value : string = null
Return values
mixed —addFilter()
public
addFilter(callable $filter) : mixed
Parameters
- $filter : callable
Return values
mixed —addJs()
Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
public
addJs(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
- $name : string
-
Specifies a path (URL) to the script.
- $attributes : array<string|int, mixed> = []
-
Adds extra HTML attributes to the asset link.
Return values
void —addRss()
Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
public
addRss(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
- $name : string
-
Specifies a path (URL) to the RSS channel
- $attributes : array<string|int, mixed> = []
-
Adds extra HTML attributes to the asset link.
Return values
void —addViewPath()
Prepends a path on the available view path locations.
public
addViewPath(string|array<string|int, mixed> $path) : void
Parameters
- $path : string|array<string|int, mixed>
Return values
void —asExtension()
Short hand for `getClassExtension()` method, except takes the short extension name, example:
public
asExtension(string $shortName) : mixed
$this->asExtension('FormController')
Parameters
- $shortName : string
Return values
mixed —bindToController()
Binds a widget to the controller for safe use.
public
bindToController() : void
Return values
void —clearExtendedClasses()
Clear the list of extended classes so they will be re-extended.
public
static clearExtendedClasses() : void
Return values
void —clearUserPreference()
Clears a single preference key from the user preferences for this controller/widget.
public
clearUserPreference(string $key) : void
Parameters
- $key : string
-
Unique key for the data store.
Return values
void —clearUserPreferences()
Clears all user preferences for this controller/widget.
public
clearUserPreferences() : void
Return values
void —combineAssets()
Run the provided assets through the Asset Combiner
public
combineAssets(array<string|int, mixed> $assets[, string $localPath = '' ]) : string
Parameters
- $assets : array<string|int, mixed>
-
Collection of assets
- $localPath : string = ''
-
Prefix all assets with this path (optional)
Return values
string —extend()
public
static extend(callable $callback) : mixed
Parameters
- $callback : callable
Return values
mixed —extendableCall()
Magic method for `__call()`
public
extendableCall(string $name[, array<string|int, mixed> $params = null ]) : mixed
Parameters
- $name : string
- $params : array<string|int, mixed> = null
Return values
mixed —extendableCallStatic()
Magic method for `__callStatic()`
public
static extendableCallStatic(string $name[, array<string|int, mixed> $params = null ]) : mixed
Parameters
- $name : string
- $params : array<string|int, mixed> = null
Return values
mixed —extendableConstruct()
This method should be called as part of the constructor.
public
extendableConstruct() : mixed
Return values
mixed —extendableExtendCallback()
Helper method for `::extend()` static method
public
static extendableExtendCallback(callable $callback) : void
Parameters
- $callback : callable
Return values
void —extendableGet()
Magic method for `__get()`
public
extendableGet(string $name) : string
Parameters
- $name : string
Return values
string —extendableSet()
Magic method for `__set()`
public
extendableSet(string $name, string $value) : string
Parameters
- $name : string
- $value : string
Return values
string —extendClassWith()
Dynamically extend a class with a specified behavior
public
extendClassWith(string $extensionName) : void
Parameters
- $extensionName : string
Return values
void —fireSystemEvent()
Fires a combination of local and global events. The first segment is removed from the event name locally and the local object is passed as the first argument to the event globally. Halting is also enabled by default.
public
fireSystemEvent(string $event[, array<string|int, mixed> $params = [] ][, bool $halt = true ]) : mixed
For example:
$this->fireSystemEvent('backend.list.myEvent', ['my value']);
Is equivalent to:
$this->fireEvent('list.myEvent', ['myvalue'], true);
Event::fire('backend.list.myEvent', [$this, 'myvalue'], true);
Parameters
- $event : string
-
Event name
- $params : array<string|int, mixed> = []
-
Event parameters
- $halt : bool = true
-
Halt after first non-null result
Return values
mixed —fireViewEvent()
Special event function used for extending within view files, allowing HTML to be injected multiple times.
public
fireViewEvent(string $event[, array<string|int, mixed> $params = [] ]) : string
For example:
fireViewEvent('backend.auth.extendSigninView') ?>Parameters
- $event : string
-
Event name
- $params : array<string|int, mixed> = []
-
Event parameters
Return values
string —flushAssets()
Disables the use, and subequent broadcast, of assets. This is useful to call during an AJAX request to speed things up. This method works by specifically targeting the hasAssetsDefined method.
public
flushAssets() : void
Return values
void —getAssetPath()
Locates a file based on it's definition. If the file starts with a forward slash, it will be returned in context of the application public path, otherwise it will be returned in context of the asset path.
public
getAssetPath(string $fileName[, string $assetPath = null ]) : string
Parameters
- $fileName : string
-
File to load.
- $assetPath : string = null
-
Explicitly define an asset path.
Return values
string —Relative path to the asset file.
getAssetPaths()
Returns an array of all registered asset paths.
public
getAssetPaths() : array<string|int, mixed>
Return values
array<string|int, mixed> —getClassExtension()
Returns a behavior object from an extendable class, example:
public
getClassExtension(string $name) : mixed
$this->getClassExtension('Backend.Behaviors.FormController')
Parameters
- $name : string
-
Fully qualified behavior name
Return values
mixed —getClassMethods()
Get a list of class methods, extension equivalent of get_class_methods()
public
getClassMethods() : array<string|int, mixed>
Return values
array<string|int, mixed> —getColumn()
Get a specified column object
public
getColumn(string $column) : mixed
Parameters
- $column : string
Return values
mixed —getColumns()
Get all the registered columns for the instance.
public
getColumns() : array<string|int, mixed>
Return values
array<string|int, mixed> —getColumnValue()
Returns a column value, with filters applied
public
getColumnValue(mixed $record, mixed $column) : string
Parameters
- $record : mixed
- $column : mixed
Return values
string —getColumnValueRaw()
Returns a raw column value
public
getColumnValueRaw(mixed $record, mixed $column) : string
Parameters
- $record : mixed
- $column : mixed
Return values
string —getConfig()
Safe accessor for configuration values.
public
getConfig(string $name[, string $default = null ]) : string
Parameters
- $name : string
-
Config name, supports array names like "field[key]"
- $default : string = null
-
Default value if nothing is found
Return values
string —getConfigPath()
Locates a file based on it's definition. If the file starts with the ~ symbol it will be returned in context of the application base path, otherwise it will be returned in context of the config path.
public
getConfigPath(string $fileName[, mixed $configPath = null ]) : string
Parameters
- $fileName : string
-
File to load.
- $configPath : mixed = null
-
Explicitly define a config path.
Return values
string —Full path to the config file.
getController()
Returns the controller using this widget.
public
getController() : mixed
Return values
mixed —getDynamicProperties()
Returns all dynamic properties and their values
public
getDynamicProperties() : array<string|int, mixed>
Return values
array<string|int, mixed> —['property' => 'value']
getEventHandler()
Returns a fully qualified event handler name for this widget.
public
getEventHandler(string $name) : string
Parameters
- $name : string
-
The ajax event handler name.
Return values
string —getFatalError()
public
getFatalError() : string
Return values
string —The fatal error message
getHeaderValue()
Looks up the column header
public
getHeaderValue(mixed $column) : mixed
Parameters
- $column : mixed
Return values
mixed —getId()
Returns a unique ID for this widget. Useful in creating HTML markup.
public
getId([string $suffix = null ]) : string
Parameters
- $suffix : string = null
-
An extra string to append to the ID.
Return values
string —A unique identifier.
getRecordOnClick()
Returns the onclick event for a list row.
public
getRecordOnClick(Model $record) : string
Parameters
- $record : Model
Return values
string —getRecordUrl()
Returns the record URL address for a list row.
public
getRecordUrl(Model $record) : string
Parameters
- $record : Model
Return values
string —getRowClass()
Adds a custom CSS class string to a record row
public
getRowClass(Model $record) : string
Parameters
- $record : Model
-
Populated model
Return values
string —getSortColumn()
Returns the current sorting column, saved in a session or cached.
public
getSortColumn() : mixed
Return values
mixed —getSortDirection()
public
getSortDirection() : mixed
Return values
mixed —getUserPreference()
Retrieves a widget related key/value pair from the user preferences
public
getUserPreference([string $key = null ][, mixed $default = null ]) : mixed
Parameters
- $key : string = null
-
Unique key for the data store.
- $default : mixed = null
-
A default value to use when value is not found.
Return values
mixed —getUserPreferences()
Retrieves and caches all user preferences for this particular controller/widget.
public
getUserPreferences() : array<string|int, mixed>
Return values
array<string|int, mixed> —getViewPath()
Locates a file based on its definition. The file name can be prefixed with a symbol (~|$) to return in context of the application or plugin base path, otherwise it will be returned in context of this object view path.
public
getViewPath(string $fileName[, mixed $viewPath = null ]) : string
Parameters
- $fileName : string
-
File to load.
- $viewPath : mixed = null
-
Explicitly define a view path.
Return values
string —Full path to the view file.
getViewPaths()
Returns the active view path locations.
public
getViewPaths() : array<string|int, mixed>
Return values
array<string|int, mixed> —getVisibleColumns()
Returns the list columns that are visible by list settings or default
public
getVisibleColumns() : mixed
Return values
mixed —guessConfigPath()
Guess the package path for the called class.
public
guessConfigPath([string $suffix = '' ]) : string
Parameters
- $suffix : string = ''
-
An extra path to attach to the end
Return values
string —guessConfigPathFrom()
Guess the package path from a specified class.
public
guessConfigPathFrom(string $class[, string $suffix = '' ]) : string
Parameters
- $class : string
-
Class to guess path from.
- $suffix : string = ''
-
An extra path to attach to the end
Return values
string —guessViewPath()
Guess the package path for the called class.
public
guessViewPath([string $suffix = '' ][, bool $isPublic = false ]) : string
Parameters
- $suffix : string = ''
-
An extra path to attach to the end
- $isPublic : bool = false
-
Returns public path instead of an absolute one
Return values
string —guessViewPathFrom()
Guess the package path from a specified class.
public
guessViewPathFrom(string $class[, string $suffix = '' ][, bool $isPublic = false ]) : string
Parameters
- $class : string
-
Class to guess path from.
- $suffix : string = ''
-
An extra path to attach to the end
- $isPublic : bool = false
-
Returns public path instead of an absolute one
Return values
string —handleError()
Sets standard page variables in the case of a controller error.
public
handleError(mixed $exception) : mixed
Parameters
- $exception : mixed
Return values
mixed —hasAssetsDefined()
Returns true if assets any have been added.
public
hasAssetsDefined() : bool
Return values
bool —hasFatalError()
public
hasFatalError() : bool
Return values
bool —Whether a fatal error has been set or not.
init()
Initialize the widget, called by the constructor and free from its parameters.
public
init() : void
Return values
void —isClassExtendedWith()
Check if extendable class is extended with a behavior object
public
isClassExtendedWith(string $name) : bool
Parameters
- $name : string
-
Fully qualified behavior name
Return values
bool —isTreeNodeExpanded()
Checks if a node (model) is expanded in the session.
public
isTreeNodeExpanded(Model $node) : bool
Parameters
- $node : Model
Return values
bool —makeAssets()
Outputs `<link>` and `<script>` tags to load assets previously added with addJs and addCss method calls
public
makeAssets([string $type = null ]) : string
Parameters
- $type : string = null
-
Return an asset collection of a given type (css, rss, js) or null for all.
Return values
string —makeConfig()
Reads the contents of the supplied file and applies it to this object.
public
makeConfig([array<string|int, mixed> $configFile = [] ][, array<string|int, mixed> $requiredConfig = [] ]) : array<string|int, mixed>|stdClass
Parameters
- $configFile : array<string|int, mixed> = []
- $requiredConfig : array<string|int, mixed> = []
Return values
array<string|int, mixed>|stdClass —makeConfigFromArray()
Makes a config object from an array, making the first level keys properties of a new object.
public
makeConfigFromArray([array<string|int, mixed> $configArray = [] ]) : stdClass
Parameters
- $configArray : array<string|int, mixed> = []
-
Config array.
Return values
stdClass —The config object
makeFileContents()
Includes a file path using output buffering.
public
makeFileContents(string $filePath[, array<string|int, mixed> $extraParams = [] ]) : string
Ensures that vars are available.
Parameters
- $filePath : string
-
Absolute path to the view file.
- $extraParams : array<string|int, mixed> = []
-
Parameters that should be available to the view.
Return values
string —makeFormWidget()
Makes a form widget object with the supplied form field and widget configuration.
public
makeFormWidget(string $class[, mixed $fieldConfig = [] ][, array<string|int, mixed> $widgetConfig = [] ]) : FormWidgetBase
Parameters
- $class : string
-
Widget class name
- $fieldConfig : mixed = []
-
A field name, an array of config or a FormField object.
- $widgetConfig : array<string|int, mixed> = []
-
An array of config.
Return values
FormWidgetBase —The widget object
makeLayout()
Render a layout.
public
makeLayout([string $name = null ][, array<string|int, mixed> $params = [] ][, bool $throwException = true ]) : mixed
Parameters
- $name : string = null
-
Specifies the layout name. If this parameter is omitted, the $layout property will be used.
- $params : array<string|int, mixed> = []
-
Parameter variables to pass to the view.
- $throwException : bool = true
-
Throw an exception if the layout is not found
Return values
mixed —The layout contents, or false.
makeLayoutPartial()
Renders a layout partial
public
makeLayoutPartial(string $partial[, array<string|int, mixed> $params = [] ]) : string
Parameters
- $partial : string
-
The view to load.
- $params : array<string|int, mixed> = []
-
Parameter variables to pass to the view.
Return values
string —The layout partial contents
makePartial()
Render a partial file contents located in the views folder.
public
makePartial(string $partial[, array<string|int, mixed> $params = [] ][, bool $throwException = true ]) : mixed
Parameters
- $partial : string
-
The view to load.
- $params : array<string|int, mixed> = []
-
Parameter variables to pass to the view.
- $throwException : bool = true
-
Throw an exception if the partial is not found.
Return values
mixed —Partial contents or false if not throwing an exception.
makeView()
Loads a view with the name specified. Applies layout if its name is provided by the parent object.
public
makeView(string $view) : string
The view file must be situated in the views directory, and has the extension "htm".
Parameters
- $view : string
-
Specifies the view name, without extension. Eg: "index".
Return values
string —makeViewContent()
Renders supplied contents inside a layout.
public
makeViewContent(string $contents[, string $layout = null ]) : string
Parameters
- $contents : string
-
The inner contents as a string.
- $layout : string = null
-
Specifies the layout name.
Return values
string —makeWidget()
Makes a widget object with the supplied configuration file.
public
makeWidget(string $class[, array<string|int, mixed> $widgetConfig = [] ]) : mixed|WidgetBase
Parameters
- $class : string
-
Widget class name
- $widgetConfig : array<string|int, mixed> = []
-
An array of config.
Return values
mixed|WidgetBase —The widget object
mergeConfig()
Merges two configuration sources, either prepared or not, and returns them as a single configuration object.
public
mergeConfig(mixed $configA, mixed $configB) : stdClass
Parameters
- $configA : mixed
- $configB : mixed
Return values
stdClass —The config object
methodExists()
Checks if a method exists, extension equivalent of method_exists()
public
methodExists(string $name) : bool
Parameters
- $name : string
Return values
bool —onApplySetup()
Event handler to apply the list set up.
public
onApplySetup() : mixed
Return values
mixed —onFilter()
Event handler for changing the filter
public
onFilter() : mixed
Return values
mixed —onLoadSetup()
Event handler to display the list set up.
public
onLoadSetup() : mixed
Return values
mixed —onPaginate()
Event handler for switching the page number.
public
onPaginate() : mixed
Return values
mixed —onRefresh()
Event handler for refreshing the list.
public
onRefresh() : mixed
Return values
mixed —onResetSetup()
Event handler to apply the list set up.
public
onResetSetup() : mixed
Return values
mixed —onSort()
Event handler for sorting the list.
public
onSort() : mixed
Return values
mixed —onToggleTreeNode()
Sets a node (model) to an expanded or collapsed state, stored in the session, then renders the list again.
public
onToggleTreeNode() : string
Return values
string —List HTML contents.
prepareModel()
public
prepareModel() : mixed
Return values
mixed —prepareQuery()
Applies any filters to the model.
public
prepareQuery() : mixed
Return values
mixed —prepareVars()
Prepares the list data
public
prepareVars() : mixed
Return values
mixed —propertyExists()
Checks if a property exists, extension equivalent of `property_exists()`
public
propertyExists(string $name) : bool
Parameters
- $name : string
Return values
bool —putUserPreference()
Saves a widget related key/value pair in to the users preferences
public
putUserPreference(string $key, mixed $value) : void
Parameters
- $key : string
-
Unique key for the data store.
- $value : mixed
-
The value to store.
Return values
void —removeColumn()
Programatically remove a column, used for extensibility.
public
removeColumn(mixed $columnName) : mixed
Parameters
- $columnName : mixed
Return values
mixed —render()
Renders the widget.
public
render() : string
Return values
string —HTML markup supplied by this widget.
resetSession()
Resets all session data related to this widget.
public
resetSession() : void
Return values
void —setSearchOptions()
Applies a search options to the list search.
public
setSearchOptions([array<string|int, mixed> $options = [] ]) : mixed
Parameters
- $options : array<string|int, mixed> = []
Return values
mixed —setSearchTerm()
Applies a search term to the list results, searching will disable tree view if a value is supplied.
public
setSearchTerm(string $term[, bool $resetPagination = false ]) : mixed
Parameters
- $term : string
- $resetPagination : bool = false
Return values
mixed —validateTree()
Validates the model and settings if showTree is used
public
validateTree() : void
Return values
void —addAsset()
Adds the provided asset to the internal asset collections
protected
addAsset(string $type, string $path, array<string|int, mixed> $attributes) : mixed
Parameters
- $type : string
-
The type of the asset: 'js' || 'css' || 'rss'
- $path : string
-
The path to the asset
- $attributes : array<string|int, mixed>
-
The attributes for the asset
Return values
mixed —applySearchToQuery()
Applies the search constraint to a query.
protected
applySearchToQuery(mixed $query, mixed $columns[, mixed $boolean = 'and' ]) : mixed
Parameters
- $query : mixed
- $columns : mixed
- $boolean : mixed = 'and'
Return values
mixed —defineListColumns()
Builds an array of list columns with keys as the column name and values as a ListColumn object.
protected
defineListColumns() : mixed
Return values
mixed —evalColorPickerTypeValue()
Process as background color, to be seen at list
protected
evalColorPickerTypeValue(mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —evalCustomListType()
Process a custom list types registered by plugins.
protected
evalCustomListType(mixed $type, mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $type : mixed
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —evalDatetimeTypeValue()
Process as a datetime value
protected
evalDatetimeTypeValue(mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —evalDateTypeValue()
Process as a date value
protected
evalDateTypeValue(mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —evalNumberTypeValue()
Process as number, proxy to text
protected
evalNumberTypeValue(mixed $record, mixed $column, mixed $value) : string
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
string —evalPartialTypeValue()
Process as partial reference
protected
evalPartialTypeValue(mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —evalSwitchTypeValue()
Process as boolean switch
protected
evalSwitchTypeValue(mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —evalTextTypeValue()
Process as text, escape the value
protected
evalTextTypeValue(mixed $record, mixed $column, mixed $value) : string
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
string —evalTimesinceTypeValue()
Process as diff for humans (1 min ago)
protected
evalTimesinceTypeValue(mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —evalTimetenseTypeValue()
Process as time as current tense (Today at 0:00)
protected
evalTimetenseTypeValue(mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —evalTimeTypeValue()
Process as a time value
protected
evalTimeTypeValue(mixed $record, mixed $column, mixed $value) : mixed
Parameters
- $record : mixed
- $column : mixed
- $value : mixed
Return values
mixed —extendableIsAccessible()
Checks if a property is accessible, property equivalent of `is_callable()`
protected
extendableIsAccessible(mixed $class, string $propertyName) : bool
Parameters
- $class : mixed
- $propertyName : string
Return values
bool —extensionExtractMethods()
Extracts the available methods from a behavior and adds it to the list of callable methods.
protected
extensionExtractMethods(string $extensionName, object $extensionObject) : void
Parameters
- $extensionName : string
- $extensionObject : object
Return values
void —fillFromConfig()
Transfers config values stored inside the $config property directly on to the root object properties. If no properties are defined all config will be transferred if it finds a matching property.
protected
fillFromConfig([array<string|int, mixed> $properties = null ]) : void
Parameters
- $properties : array<string|int, mixed> = null
Return values
void —getAssetEntryBuildPath()
Internal helper, attaches a build code to an asset path
protected
getAssetEntryBuildPath(array<string|int, mixed> $asset) : string
Parameters
- $asset : array<string|int, mixed>
-
Stored asset array
Return values
string —getAssetScheme()
Internal helper, get asset scheme
protected
getAssetScheme(string $asset) : string
Parameters
- $asset : string
-
Specifies a path (URL) to the asset.
Return values
string —getCurrentPageNumber()
Returns the current page number for the list.
protected
getCurrentPageNumber(object $query) : int
This will override the current page number provided by the user if it is past the last page of available records.
Parameters
- $query : object
Return values
int —getLocalPath()
protected
getLocalPath(string $relativePath) : mixed
Parameters
- $relativePath : string
Return values
mixed —getPreferenceKey()
Returns a unique identifier for this widget and controller action for preference storage.
protected
getPreferenceKey() : string
Return values
string —getPreferenceStorage()
Specifies the model used for storing the user preferences.
protected
getPreferenceStorage() : Model
Return values
Model —getRecords()
Returns all the records from the supplied model, after filtering.
protected
getRecords() : Collection
Return values
Collection —getSearchableColumns()
Returns a collection of columns which can be searched.
protected
getSearchableColumns() : array<string|int, mixed>
Return values
array<string|int, mixed> —getSession()
Retrieves a widget related key/value pair from session data.
protected
getSession([string $key = null ][, string $default = null ]) : string
Parameters
- $key : string = null
-
Unique key for the data store.
- $default : string = null
-
A default value to use when value is not found.
Return values
string —getSetupListColumns()
Returns all the list columns used for list set up.
protected
getSetupListColumns() : mixed
Return values
mixed —getSetupPerPageOptions()
Returns an array of allowable records per page.
protected
getSetupPerPageOptions() : mixed
Return values
mixed —getSortableColumns()
Returns a collection of columns which are sortable.
protected
getSortableColumns() : mixed
Return values
mixed —getTotalColumns()
Calculates the total columns used in the list, including checkboxes and other additions.
protected
getTotalColumns() : mixed
Return values
mixed —handleViewException()
Handle a view exception.
protected
handleViewException(Exception $e, int $obLevel) : void
Parameters
- $e : Exception
- $obLevel : int
Return values
void —isColumnPivot()
Checks if a column refers to a pivot model specifically.
protected
isColumnPivot(ListColumn $column) : bool
Parameters
- $column : ListColumn
-
List column object
Return values
bool —isColumnRelated()
Check if column refers to a relation of the model
protected
isColumnRelated(ListColumn $column[, bool $multi = false ]) : bool
Parameters
- $column : ListColumn
-
List column object
- $multi : bool = false
-
If set, returns true only if the relation is a "multiple relation type"
Return values
bool —isSortable()
Returns true if the column can be sorted.
protected
isSortable([mixed $column = null ]) : mixed
Parameters
- $column : mixed = null
Return values
mixed —loadAssets()
Adds widget specific asset files. Use $this->addJs() and $this->addCss() to register new assets to include on the page.
protected
loadAssets() : void
Tags
Return values
void —makeListColumn()
Creates a list column object from it's name and configuration.
protected
makeListColumn(mixed $name, mixed $config) : mixed
Parameters
- $name : mixed
- $config : mixed
Return values
mixed —makeSessionId()
Returns a unique session identifier for this widget and controller action.
protected
makeSessionId() : string
Return values
string —parseTableName()
Replaces the @ symbol with a table name in a model
protected
parseTableName(string $sql, string $table) : string
Parameters
- $sql : string
- $table : string
Return values
string —putSession()
Saves a widget related key/value pair in to session data.
protected
putSession(string $key, string $value) : void
Parameters
- $key : string
-
Unique key for the data store.
- $value : string
-
The value to store.
Return values
void —removeDuplicates()
Removes duplicate assets from the entire collection.
protected
removeDuplicates() : void
Return values
void —validateDateTimeValue()
Validates a column type as a date
protected
validateDateTimeValue(mixed $value, mixed $column) : mixed
Parameters
- $value : mixed
- $column : mixed
Return values
mixed —validateModel()
Validate the supplied form model.
protected
validateModel() : void