ListController

Adds features for working with backend lists.

 class Backend\Behaviors\ListController
extends Backend\Classes\ControllerBehavior

This behavior is implemented in the controller like so:

public $implement = [
    \Backend\Behaviors\ListController::class,
];

public $listConfig = 'config_list.yaml';

The $listConfig property makes reference to the list configuration values as either a YAML file, located in the controller view directory, or directly as a PHP array.

Extends

Class Description
ControllerBehavior

Controller Behavior base class

Traits

Trait Description
AssetMaker

Asset Maker Trait Adds asset based methods to a class

ConfigMaker

Config Maker Trait Adds configuration based methods to a class

ExtensionTrait

Extension trait

SessionMaker

Session Maker Trait

ViewMaker

View Maker Trait Adds view based methods to a class

WidgetMaker

Widget Maker Trait

Properties

public $listConfig : mixed

Configuration for this behaviour

protected $actions : array

Visible actions in context of the controller

protected $filterWidgets : \Backend\Classes\WidgetBase[]

Reference to the filter widget objects.

protected $listDefinitions : array

List definitions, keys for alias and value for configuration.

protected $listWidgets : \Backend\Classes\WidgetBase[]

Reference to the list widget object.

protected $primaryDefinition : string

The primary list alias to use. Default: list

protected $requiredConfig : array

Configuration values that must exist when applying the primary config file.

  • modelClass: Class name for the model
  • list: List column definitions

protected $toolbarWidgets : \Backend\Classes\WidgetBase[]

Reference to the toolbar widget objects.

inherited public $assetPath : string

Inherited from AssetMaker

Specifies a path to the asset directory.

inherited public static $extendableStaticCalledClass : string

Inherited from ExtensionTrait

The calling class when using a static method.

inherited public $layout : string

Inherited from ViewMaker

Layout to use for the view.

inherited public $suppressLayout : bool

Inherited from ViewMaker

Prevents the use of a layout.

inherited public $vars : array

Inherited from ViewMaker

A list of variables to pass to the page.

inherited protected $assets : array

Inherited from AssetMaker

Collection of assets to display in the layout.

inherited protected $config : array

Inherited from ControllerBehavior

Supplied configuration.

inherited protected $configPath : string

Inherited from ConfigMaker

Specifies a path to the config directory.

inherited protected $controller : Backend\Classes\Controller

Inherited from ControllerBehavior

Reference to the back end controller.

inherited protected static $extensionCallbacks : array

Inherited from ExtensionTrait

Used to extend the constructor of an extension class. Eg:

BehaviorClass::extend(function($obj) { })

inherited protected $extensionHidden : mixed

Inherited from ExtensionTrait

inherited protected $layoutPath : string

Inherited from ViewMaker

Specifies a path to the layout directory.

inherited protected $orderFactor : integer

Inherited from AssetMaker

Ensures "first-come, first-served" applies to assets of the same ordering.

inherited protected $requiredProperties : array

Inherited from ControllerBehavior

Properties that must exist in the controller using this behavior.

inherited protected $viewPath : string | array

Inherited from ViewMaker

Specifies a path to the views directory.

Methods

public __construct (Backend\Classes\Controller $controller)

Behavior constructor

Parameters
Property Description
$controller
Returns
mixed

public static extendListColumns (callable $callback) : void

Static helper for extending list columns.

Parameters
Property Description
$callback
callable
Returns
void

public static extendListFilterScopes (callable $callback) : void

Static helper for extending filter scopes.

Parameters
Property Description
$callback
callable
Returns
void

public index () : void

Index Controller action.

Returns
void

public index_onDelete () : void

Bulk delete records.

Returns
void

public listExtendColumns (Backend\Widgets\Lists $host) : void

Called after the list columns are defined.

Parameters
Property Description
$host

The hosting list widget

Returns
void

public listExtendColumnsBefore (Backend\Widgets\Lists $host) : void

Called before the list columns are defined.

Parameters
Property Description
$host

The hosting list widget

Returns
void

public listExtendModel (Winter\Storm\Database\Model $model, string | null $definition = null) : Winter\Storm\Database\Model

Controller override: Extend supplied model

Parameters
Property Description
$model
$definition
string | null
Returns

public listExtendQuery (Winter\Storm\Database\Builder $query, string | null $definition = null)

Controller override: Extend the query used for populating the list after the default query is processed.

Parameters
Property Description
$query
$definition
string | null
Returns
mixed

public listExtendQueryBefore (Winter\Storm\Database\Builder $query, string | null $definition = null)

Controller override: Extend the query used for populating the list before the default query is processed.

Parameters
Property Description
$query
$definition
string | null
Returns
mixed

public listExtendRecords (Illuminate\Contracts\Pagination\LengthAwarePaginator | Illuminate\Database\Eloquent\Collection $records, string | null $definition = null)

Controller override: Extend the records used for populating the list after the query is processed.

Parameters
Property Description
$records
Illuminate\Contracts\Pagination\LengthAwarePaginator | Illuminate\Database\Eloquent\Collection
$definition
string | null
Returns
mixed

public listFilterExtendQuery (Winter\Storm\Database\Builder $query, array $scope)

Controller override: Extend the query used for populating the filter options before the default query is processed.

Parameters
Property Description
$query
$scope
array
Returns
mixed

public listFilterExtendScopes (Backend\Widgets\Filter $host) : void

Called after the filter scopes are defined.

Parameters
Property Description
$host

The hosting filter widget

Returns
void

public listGetConfig ($definition = null) : stdClass

Returns the configuration used by this behavior.

Parameters
Property Description
$definition
mixed
Returns
stdClass

public listGetWidget ($definition = null) : Backend\Classes\WidgetBase

Returns the widget used by this behavior.

Parameters
Property Description
$definition
mixed
Returns

public listInjectRowClass (Winter\Storm\Database\Model $record, string | null $definition = null) : string | void

Returns a CSS class name for a list row (

).
Parameters
Property Description
$record

The populated model used for the column

$definition
string | null

List definition (optional)

Returns
string | void

CSS class name

public listMakePartial (string $partial, array $params = []) : string

Controller accessor for making partials within this behavior.

Parameters
Property Description
$partial
string
$params
array
Returns
string

Partial contents

public listOverrideColumnValue (Winter\Storm\Database\Model $record, string $columnName, string | null $definition = null) : string | void

Replace a table column value (

...)
Parameters
Property Description
$record

The populated model used for the column

$columnName
string

The column name to override

$definition
string | null

List definition (optional)

Returns
string | void

HTML view

public listOverrideHeaderValue (string $columnName, string | null $definition = null) : string | void

Replace the entire table header contents (

...) with custom HTML
Parameters
Property Description
$columnName
string

The column name to override

$definition
string | null

List definition (optional)

Returns
string | void

HTML view

public listRefresh ($definition = null) : array

Refreshes the list container only, useful for returning in custom AJAX requests.

Parameters
Property Description
$definition
mixed
Returns
array

The list element selector as the key, and the list contents are the value.

public listRender (string $definition = null) : string

Renders the widget collection.

Parameters
Property Description
$definition
string

Optional list definition.

Returns
string

Rendered HTML for the list.

public makeList ($definition = null) : Backend\Widgets\Lists

Prepare the widgets used by this action

Parameters
Property Description
$definition
mixed
Returns

public makeLists () : array

Creates all the list widgets based on the definitions.

Returns
array

inherited public addCss (string | array $name, array $attributes = []) : void

Inherited from AssetMaker

Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

Parameters
Property Description
$name
string | array

When an array of paths are provided they will be passed to the Asset Combiner

$attributes
array

When a string is provided it will be used as the 'build' attribute value

Returns
void

inherited public addJs (string | array $name, array $attributes = []) : void

Inherited from AssetMaker

Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

Parameters
Property Description
$name
string | array

When an array of paths are provided they will be passed to the Asset Combiner

$attributes
array

When a string is provided it will be used as the 'build' attribute value

Returns
void

inherited public addRss (string $name, array $attributes = []) : void

Inherited from AssetMaker

Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

Parameters
Property Description
$name
string
$attributes
array
Returns
void

inherited public addViewPath (string | array $path) : void

Inherited from ViewMaker

Prepends a path on the available view path locations.

Parameters
Property Description
$path
string | array
Returns
void

inherited public addVite (array | string $entrypoints, ?string $package = null) : void

Inherited from AssetMaker

Adds Vite tags

Parameters
Property Description
$entrypoints
array | string

The list of entry points for Vite

$package
?string

The package name of the plugin or theme

Returns
void

inherited public combineAssets (array $assets, string $localPath = "") : string

Inherited from AssetMaker

Run the provided assets through the Asset Combiner

Parameters
Property Description
$assets
array
$localPath
string
Returns
string

inherited public static extend (callable $callback)

Inherited from ExtensionBase
Parameters
Property Description
$callback
callable
Returns
mixed

inherited public extensionApplyInitCallbacks ()

Inherited from ExtensionTrait
Returns
mixed

inherited public static extensionExtendCallback (callable $callback) : void

Inherited from ExtensionTrait

Helper method for ::extend() static method

Parameters
Property Description
$callback
callable
Returns
void

inherited public extensionIsHiddenField ($name)

Inherited from ExtensionTrait
Parameters
Property Description
$name
mixed
Returns
mixed

inherited public extensionIsHiddenMethod ($name)

Inherited from ExtensionTrait
Parameters
Property Description
$name
mixed
Returns
mixed

inherited public flushAssets () : void

Inherited from AssetMaker

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.

Returns
void

inherited public getAssetPath (string $fileName, $assetPath = null) : string

Inherited from AssetMaker

Returns the URL to the provided asset. If the provided fileName is a relative path without a leading slash it will be assumbed to be relative to the asset path.

Parameters
Property Description
$fileName
string
$assetPath
mixed
Returns
string

inherited public getAssetPaths () : array

Inherited from AssetMaker

Returns an array of all registered asset paths.

Assets will be prioritized based on their defined ordering.

Returns
array

inherited public static getCalledExtensionClass ()

Inherited from ExtensionTrait
Returns
mixed

inherited public getConfig (string $name = null, mixed $default = null) : string

Inherited from ControllerBehavior

Safe accessor for configuration values.

Parameters
Property Description
$name
string

Config name, supports array names like "field[key]"

$default
mixed

Default value if nothing is found

Returns
string

inherited public getConfigPath (string $fileName, mixed $configPath = null) : string

Inherited from ConfigMaker

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.

Parameters
Property Description
$fileName
string

File to load.

$configPath
mixed

Explicitly define a config path.

Returns
string

Full path to the config file.

inherited public getViewPath (string $fileName, $viewPaths = null) : string

Inherited from ViewMaker

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.

If the fileName cannot be found it will be returned unmodified.

Parameters
Property Description
$fileName
string
$viewPaths
mixed
Returns
string

inherited public getViewPaths () : array

Inherited from ViewMaker

Returns the active view path locations.

Returns
array

inherited public guessConfigPath (string $suffix = "") : string

Inherited from ConfigMaker

Guess the package path for the called class.

Parameters
Property Description
$suffix
string

An extra path to attach to the end

Returns
string

inherited public guessConfigPathFrom (string $class, string $suffix = "") : string

Inherited from ConfigMaker

Guess the package path from a specified class.

Parameters
Property Description
$class
string

Class to guess path from.

$suffix
string

An extra path to attach to the end

Returns
string

inherited public guessViewPath (string $suffix = "", boolean $isPublic = false) : string | null

Inherited from ViewMaker

Guess the package path for the called class.

Parameters
Property Description
$suffix
string

An extra path to attach to the end

$isPublic
boolean

Returns public path instead of an absolute one

Returns
string | null

inherited public guessViewPathFrom (string $class, string $suffix = "", boolean $isPublic = false) : string | null

Inherited from ViewMaker

Guess the package path from a specified class.

Parameters
Property Description
$class
string

Class to guess path from.

$suffix
string

An extra path to attach to the end

$isPublic
boolean

Returns public path instead of an absolute one

Returns
string | null

inherited public hasAssetsDefined () : bool

Inherited from AssetMaker

Returns true if assets any have been added.

Returns
bool

inherited public makeAssets ($type = null) : string | null

Inherited from AssetMaker

Outputs <link> and <script> tags to load assets previously added with addJs, addCss, & addRss method calls depending on the provided $type

Parameters
Property Description
$type
mixed
Returns
string | null

inherited public makeConfig (array $configFile = [], array $requiredConfig = []) : array | stdClass

Inherited from ConfigMaker

Reads the contents of the supplied file and applies it to this object.

Parameters
Property Description
$configFile
array
$requiredConfig
array
Returns
array | stdClass

inherited public makeConfigFromArray (array $configArray = []) : stdClass

Inherited from ConfigMaker

Makes a config object from an array, making the first level keys properties of a new object.

Parameters
Property Description
$configArray
array

Config array.

Returns
stdClass

The config object

inherited public makeFileContents (string $filePath, array $extraParams = []) : string

Inherited from ControllerBehavior

Makes all views in context of the controller, not the behavior.

Parameters
Property Description
$filePath
string

Absolute path to the view file.

$extraParams
array

Parameters that should be available to the view.

Returns
string

inherited public makeFormWidget (string $class, array $fieldConfig = [], array $widgetConfig = []) : Backend\Classes\FormWidgetBase

Inherited from WidgetMaker

Makes a form widget object with the supplied form field and widget configuration.

Parameters
Property Description
$class
string

Widget class name

$fieldConfig
array

A field name, an array of config or a FormField object.

$widgetConfig
array

An array of config.

Returns

The widget object

inherited public makeLayout ($name = null, array $params = [], boolean $throwException = true) : string | bool

Inherited from ViewMaker

Render a layout, defaulting to the layout propery specified on the class

Parameters
Property Description
$name
mixed
$params
array
$throwException
boolean
Returns
string | bool

The layout contents, or false.

inherited public makeLayoutPartial (string $partial, array $params = []) : string

Inherited from ViewMaker

Renders a layout partial

Parameters
Property Description
$partial
string
$params
array
Returns
string

inherited public makePartial (string $partial, array $params = [], boolean $throwException = true) : mixed

Inherited from ViewMaker

Render a partial file contents located in the views folder.

Parameters
Property Description
$partial
string
$params
array
$throwException
boolean
Returns
mixed

Partial contents or false if not throwing an exception.

inherited public makeView (string $view) : string

Inherited from ViewMaker

Loads the specified view. Applies the layout if one is set.

The view file must have the .php extension (or ".htm" for historical reasons) and be located in the views directory

Parameters
Property Description
$view
string
Returns
string

inherited public makeViewContent (string $contents, $layout = null) : string

Inherited from ViewMaker

Renders supplied contents inside a layout.

Parameters
Property Description
$contents
string
$layout
mixed
Returns
string

inherited public makeWidget (string $class, array $widgetConfig = []) : mixed | Backend\Classes\WidgetBase

Inherited from WidgetMaker

Makes a widget object with the supplied configuration file.

Parameters
Property Description
$class
string

Widget class name

$widgetConfig
array

An array of config.

Returns

The widget object

inherited public mergeConfig (mixed $configA, mixed $configB) : stdClass

Inherited from ConfigMaker

Merges two configuration sources, either prepared or not, and returns them as a single configuration object.

Parameters
Property Description
$configA
mixed
$configB
mixed
Returns
stdClass

The config object

inherited public orderAssets (array $assets) : array

Inherited from AssetMaker

Prioritize assets based on the given order.

Parameters
Property Description
$assets
array
Returns
array

inherited public resetSession () : void

Inherited from SessionMaker

Resets all session data related to this widget.

Returns
void

inherited public setConfig (mixed $config, array $required = [])

Inherited from ControllerBehavior

Sets the configuration values

Parameters
Property Description
$config
mixed

Config object or array

$required
array

Required config items

Returns
mixed

inherited protected addAsset (string $type, string $path, array $attributes) : void

Inherited from AssetMaker

Adds the provided asset to the internal asset collections

Parameters
Property Description
$type
string
$path
string
$attributes
array
Returns
void

inherited protected controllerMethodExists (string $methodName) : bool

Inherited from ControllerBehavior

Returns true in case if a specified method exists in the extended controller.

Parameters
Property Description
$methodName
string

Specifies the method name

Returns
bool

inherited protected extensionHideField ($name)

Inherited from ExtensionTrait
Parameters
Property Description
$name
mixed
Returns
mixed

inherited protected extensionHideMethod ($name)

Inherited from ExtensionTrait
Parameters
Property Description
$name
mixed
Returns
mixed

inherited protected getAssetEntryBuildPath (array $asset) : string

Inherited from AssetMaker

Internal helper, attaches a build code to an asset path

Parameters
Property Description
$asset
array
Returns
string

inherited protected getAssetScheme (string $asset) : string

Inherited from AssetMaker

Internal helper, get asset scheme

Parameters
Property Description
$asset
string
Returns
string

inherited protected getLocalPath (string | null $relativePath) : string

Inherited from AssetMaker
Parameters
Property Description
$relativePath
string | null
Returns
string

inherited protected getSession (string $key = null, string $default = null) : string

Inherited from SessionMaker

Retrieves a widget related key/value pair from session data.

Parameters
Property Description
$key
string

Unique key for the data store.

$default
string

A default value to use when value is not found.

Returns
string

inherited protected handleViewException (Throwable $e, integer $obLevel) : void

Inherited from ViewMaker

Handle a view exception.

Parameters
Property Description
$e
Throwable
$obLevel
integer
Returns
void

inherited protected hideAction (mixed $methodName)

Inherited from ControllerBehavior

Protects a public method from being available as an controller action.

These methods could be defined in a controller to override a behavior default action. Such methods should be defined as public, to allow the behavior object to access it. By default public methods of a controller are considered as actions. To prevent this occurrence, methods should be hidden by using this method.

Parameters
Property Description
$methodName
mixed

Specifies a method name.

Returns
mixed

inherited protected makeSessionId () : string

Inherited from SessionMaker

Returns a unique session identifier for this widget and controller action.

Returns
string

inherited protected putSession (string $key, mixed $value) : void

Inherited from SessionMaker

Saves a widget related key/value pair in to session data.

Parameters
Property Description
$key
string

Unique key for the data store.

$value
mixed

The value to store.

Returns
void

inherited protected removeDuplicates () : void

Inherited from AssetMaker

Removes duplicate assets from the entire collection.

Returns
void
Copyright © 2024 Winter CMS