Lists - October CMS

Contents

Backend\Widgets\Lists

Source: ~/modules/backend/widgets/Lists.php

Extends:

List Widget Used for building back end lists, renders a list of model objects

Public properties

public array $columns

List column configuration.

public Model $model

List model object.

public string $recordUrl

Link for each record row. Replace :id with the record id.

public string $recordOnClick

Click event for each record row. Replace :id with the record id.

public string $noRecordsMessage

Message to display when there are no records in the list.

public int $recordsPerPage

Maximum rows to display for each page.

public bool $showSorting

Shows the sorting options for each column.

public mixed $defaultSort

A default sort column to look for.

public bool $showCheckboxes

Display a checkbox next to each record row.

public bool $showSetup

Display the list set up used for column visibility and ordering.

public bool $showTree

Display parent/child relationships in the list.

public bool $treeExpanded

Expand the tree nodes by default.

public bool|string $showPagination

Display pagination when limiting records per page.

public bool $showPageNumbers

Display page numbers with pagination, disable to improve performance.

public string $customViewPath

Specify a custom view path to override partials used by the list.

public array $cssClasses

List of CSS classes to apply to the list container element

Show inherited public properties

Protected properties

protected $defaultAlias

A unique alias to identify this widget.

protected array $allColumns

Collection of all list columns used in this list. See also:

Backend\Classes\ListColumn

protected array $columnOverride

Override default columns with supplied key names.

protected array $visibleColumns

Columns to display and their order.

protected array $records

Model data collection.

protected int $currentPageNumber

Current page number.

protected string $searchTerm

Filter the records by a search term.

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

protected string $searchScope

Use a custom scope method for performing searches.

protected array $filterCallbacks

Collection of functions to apply to each list query.

protected array $sortableColumns

All sortable columns.

protected string $sortColumn

Sets the list sorting column.

protected string $sortDirection

Sets the list sorting direction (asc, desc)

protected static array $preferenceCache

Cache for retrieved user preferences.

Show inherited protected properties

Public methods

public void addColumns(array $columns)

Programatically add columns, used internally and for extensibility.

Parameters

array $columns - Column definitions

public void addFilter($filter)

Parameters

$filter

public void clearUserPreference(string $key)

Clears a single preference key from the user preferences for this controller/widget.

Parameters

string $key - Unique key for the data store.

public void clearUserPreferences()

Clears all user preferences for this controller/widget.

public mixed getColumn(string $column)

Get a specified column object

Parameters

string $column

public string getColumnValue($record, $column)

Returns a column value, with filters applied

Parameters

$record
$column

public string getColumnValueRaw($record, $column)

Returns a raw column value

Parameters

$record
$column

public array getColumns()

Get all the registered columns for the instance.

public void getHeaderValue($column)

Looks up the column header

Parameters

$column

public string getRecordOnClick(Model $record)

Returns the onclick event for a list row.

Parameters

Model $record

public string getRecordUrl(Model $record)

Returns the record URL address for a list row.

Parameters

Model $record

public string getRowClass(Model $record)

Adds a custom CSS class string to a record row

Parameters

Model $record - Populated model

public void getSortColumn()

Returns the current sorting column, saved in a session or cached.

public void getSortDirection()

public mixed getUserPreference(string $key=NULL, mixed $default=NULL)

Retrieves a widget related key/value pair from the user preferences

Parameters

string $key - Unique key for the data store.
mixed $default - A default value to use when value is not found.

public array getUserPreferences()

Retrieves and caches all user preferences for this particular controller/widget.

public void getVisibleColumns()

Returns the list columns that are visible by list settings or default

public void init()

Initialize the widget, called by the constructor and free from its parameters.

public boolean isTreeNodeExpanded(Model $node)

Checks if a node (model) is expanded in the session.

Parameters

Model $node

public void onApplySetup()

Event handler to apply the list set up.

public void onFilter()

Event handler for changing the filter

public void onLoadSetup()

Event handler to display the list set up.

public void onPaginate()

Event handler for switching the page number.

public void onRefresh()

Event handler for refreshing the list.

public void onResetSetup()

Event handler to apply the list set up.

public void onSort()

Event handler for sorting the list.

public string onToggleTreeNode()

Sets a node (model) to an expanded or collapsed state, stored in the session, then renders the list again.

public void prepareModel()

public void prepareQuery()

Applies any filters to the model.

public void prepareVars()

Prepares the list data

public void putUserPreference(string $key, mixed $value)

Saves a widget related key/value pair in to the users preferences

Parameters

string $key - Unique key for the data store.
mixed $value - The value to store.

public void removeColumn(string $column)

Programatically remove a column, used for extensibility.

Parameters

string $column - Column name

public void render()

Renders the widget.

public void setSearchOptions(array $options=array())

Applies a search options to the list search.

Parameters

array $options

public void setSearchTerm(string $term)

Applies a search term to the list results, searching will disable tree view if a value is supplied.

Parameters

string $term

public void validateTree()

Validates the model and settings if showTree is used

Show inherited public methods

Inherited public methods

public void __call($name, $params) - defined in October\Rain\Extension\Extendable.
public static void __callStatic($name, $params) - defined in October\Rain\Extension\Extendable.
public void __construct(Backend\Classes\Controller $controller, array $configuration=array()) - defined in Backend\Classes\WidgetBase. Constructor.
public void __get($name) - defined in October\Rain\Extension\Extendable.
public void __set($name, $value) - defined in October\Rain\Extension\Extendable.
public void addCss(string $name, array $attributes=array()) - defined in Backend\Classes\WidgetBase. Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view.
public void addDynamicMethod(string $dynamicName, callable $method, string $extension=NULL) - defined in October\Rain\Extension\Extendable. Programmatically adds a method to the extendable class.
public void addDynamicProperty(string $dynamicName, string $value=NULL) - defined in October\Rain\Extension\Extendable. Programmatically adds a property to the extendable class.
public void addJs(string $name, array $attributes=array()) - defined in Backend\Classes\WidgetBase. Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view.
public void addRss(string $name, array $attributes=array()) - defined in Backend\Classes\WidgetBase. Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view.
public void addViewPath(string|array $path) - defined in Backend\Classes\WidgetBase. Prepends a path on the available view path locations.
public mixed asExtension(string $shortName) - defined in October\Rain\Extension\Extendable. Short hand for getClassExtension() method, except takes the short.
public self bindEvent($event, $callback, $priority=0) - defined in Backend\Classes\WidgetBase. Create a new event binding.
public self bindEventOnce($event, $callback) - defined in Backend\Classes\WidgetBase. Create a new event binding that fires once only.
public void bindToController() - defined in Backend\Classes\WidgetBase. Binds a widget to the controller for safe use.
public static void clearExtendedClasses() - defined in October\Rain\Extension\Extendable. Clear the list of extended classes so they will be re-extended.
public string combineAssets(array $assets, string $localPath='') - defined in Backend\Classes\WidgetBase. Run the provided assets through the Asset Combiner.
public static void extend($callback) - defined in October\Rain\Extension\Extendable.
public void extendClassWith(string $extensionName) - defined in October\Rain\Extension\Extendable. Dynamically extend a class with a specified behavior.
public mixed extendableCall(string $name, array $params=NULL) - defined in October\Rain\Extension\Extendable. Magic method for __call().
public static mixed extendableCallStatic(string $name, array $params=NULL) - defined in October\Rain\Extension\Extendable. Magic method for __callStatic().
public void extendableConstruct() - defined in October\Rain\Extension\Extendable. This method should be called as part of the constructor.
public static void extendableExtendCallback(callable $callback) - defined in October\Rain\Extension\Extendable. Helper method for ::extend() static method.
public string extendableGet(string $name) - defined in October\Rain\Extension\Extendable. Magic method for __get().
public string extendableSet(string $name, string $value) - defined in October\Rain\Extension\Extendable. Magic method for __set().
public array fireEvent(string $event, array $params=array(), boolean $halt=false) - defined in Backend\Classes\WidgetBase. Fire an event and call the listeners.
public mixed fireSystemEvent(string $event, array $params=array(), boolean $halt=true) - defined in Backend\Classes\WidgetBase. Fires a combination of local and global events. The first segment is removed.
public string fireViewEvent(string $event, array $params=array()) - defined in Backend\Classes\WidgetBase. Special event function used for extending within view files,
public void flushAssets() - defined in Backend\Classes\WidgetBase. Disables the use, and subequent broadcast, of assets. This is useful.
public string getAssetPath(string $fileName, string $assetPath=NULL) - defined in Backend\Classes\WidgetBase. Locates a file based on it's definition. If the file starts with.
public array getAssetPaths() - defined in Backend\Classes\WidgetBase. Returns an array of all registered asset paths.
public mixed getClassExtension(string $name) - defined in October\Rain\Extension\Extendable. Returns a behavior object from an extendable class, example:.
public array getClassMethods() - defined in October\Rain\Extension\Extendable. Get a list of class methods, extension equivalent of get_class_methods().
public string getConfig(string $name, string $default=NULL) - defined in Backend\Classes\WidgetBase. Safe accessor for configuration values.
public string getConfigPath(string $fileName, mixed $configPath=NULL) - defined in Backend\Classes\WidgetBase. Locates a file based on it's definition. If the file starts with.
public void getController() - defined in Backend\Classes\WidgetBase. Returns the controller using this widget.
public array getDynamicProperties() - defined in October\Rain\Extension\Extendable. Returns all dynamic properties and their values.
public string getEventHandler(string $name) - defined in Backend\Classes\WidgetBase. Returns a fully qualified event handler name for this widget.
public string getFatalError() - defined in Backend\Classes\WidgetBase. Returns the fatal error message
public string getId(string $suffix=NULL) - defined in Backend\Classes\WidgetBase. Returns a unique ID for this widget. Useful in creating HTML markup.
public string getViewPath(string $fileName, mixed $viewPath=NULL) - defined in Backend\Classes\WidgetBase. Locates a file based on its definition. The file name can be prefixed with a.
public array getViewPaths() - defined in Backend\Classes\WidgetBase. Returns the active view path locations.
public string guessConfigPath(string $suffix='') - defined in Backend\Classes\WidgetBase. Guess the package path for the called class.
public string guessConfigPathFrom(string $class, string $suffix='') - defined in Backend\Classes\WidgetBase. Guess the package path from a specified class.
public string guessViewPath(string $suffix='', bool $isPublic=false) - defined in Backend\Classes\WidgetBase. Guess the package path for the called class.
public string guessViewPathFrom(string $class, string $suffix='', bool $isPublic=false) - defined in Backend\Classes\WidgetBase. Guess the package path from a specified class.
public void handleError($exception) - defined in Backend\Classes\WidgetBase. Sets standard page variables in the case of a controller error.
public bool hasAssetsDefined() - defined in Backend\Classes\WidgetBase. Returns true if assets any have been added.
public boolean hasFatalError() - defined in Backend\Classes\WidgetBase. Determines whether a fatal error has been set or not.
public boolean isClassExtendedWith(string $name) - defined in October\Rain\Extension\Extendable. Check if extendable class is extended with a behavior object.
public string makeAssets(string $type=NULL) - defined in Backend\Classes\WidgetBase. Outputs <link> and <script> tags to load assets previously added with addJs and addCss method calls.
public array|stdClass makeConfig(array $configFile=array(), array $requiredConfig=array()) - defined in Backend\Classes\WidgetBase. Reads the contents of the supplied file and applies it to this object.
public stdClass makeConfigFromArray(array $configArray=array()) - defined in Backend\Classes\WidgetBase. Makes a config object from an array, making the first level keys properties of a new object.
public string makeFileContents(string $filePath, array $extraParams=array()) - defined in Backend\Classes\WidgetBase. Includes a file path using output buffering.
public Backend\Classes\FormWidgetBase makeFormWidget(string $class, mixed $fieldConfig=array(), array $widgetConfig=array()) - defined in Backend\Classes\WidgetBase. Makes a form widget object with the supplied form field and widget configuration.
public mixed makeLayout(string $name=NULL, array $params=array(), bool $throwException=true) - defined in Backend\Classes\WidgetBase. Render a layout.
public string makeLayoutPartial(string $partial, array $params=array()) - defined in Backend\Classes\WidgetBase. Renders a layout partial.
public mixed makePartial(string $partial, array $params=array(), bool $throwException=true) - defined in Backend\Classes\WidgetBase. Render a partial file contents located in the views folder.
public string makeView(string $view) - defined in Backend\Classes\WidgetBase. Loads a view with the name specified. Applies layout if its name is provided by the parent object.
public string makeViewContent(string $contents, string $layout=NULL) - defined in Backend\Classes\WidgetBase. Renders supplied contents inside a layout.
public Backend\Classes\WidgetBase makeWidget(string $class, array $widgetConfig=array()) - defined in Backend\Classes\WidgetBase. Makes a widget object with the supplied configuration file.
public stdClass mergeConfig(mixed $configA, mixed $configB) - defined in Backend\Classes\WidgetBase. Merges two configuration sources, either prepared or not, and returns.
public boolean methodExists(string $name) - defined in October\Rain\Extension\Extendable. Checks if a method exists, extension equivalent of method_exists().
public boolean propertyExists(string $name) - defined in October\Rain\Extension\Extendable. Checks if a property exists, extension equivalent of property_exists().
public void resetSession() - defined in Backend\Classes\WidgetBase. Resets all session data related to this widget.
public self unbindEvent(string $event=NULL) - defined in Backend\Classes\WidgetBase. Destroys an event binding.

Protected methods

protected void applySearchToQuery($query, $columns, $boolean='and')

Applies the search constraint to a query.

Parameters

$query
$columns
$boolean

protected void defineListColumns()

Builds an array of list columns with keys as the column name and values as a ListColumn object.

protected void evalColorPickerTypeValue($record, $column, $value)

Process as background color, to be seen at list

Parameters

$record
$column
$value

protected void evalCustomListType($type, $record, $column, $value)

Process a custom list types registered by plugins.

Parameters

$type
$record
$column
$value

protected void evalDateTypeValue($record, $column, $value)

Process as a date value

Parameters

$record
$column
$value

protected void evalDatetimeTypeValue($record, $column, $value)

Process as a datetime value

Parameters

$record
$column
$value

protected string evalNumberTypeValue($record, $column, $value)

Process as number, proxy to text

Parameters

$record
$column
$value

protected void evalPartialTypeValue($record, $column, $value)

Process as partial reference

Parameters

$record
$column
$value

protected void evalSwitchTypeValue($record, $column, $value)

Process as boolean switch

Parameters

$record
$column
$value

protected string evalTextTypeValue($record, $column, $value)

Process as text, escape the value

Parameters

$record
$column
$value

protected void evalTimeTypeValue($record, $column, $value)

Process as a time value

Parameters

$record
$column
$value

protected void evalTimesinceTypeValue($record, $column, $value)

Process as diff for humans (1 min ago)

Parameters

$record
$column
$value

protected void evalTimetenseTypeValue($record, $column, $value)

Process as time as current tense (Today at 0:00)

Parameters

$record
$column
$value

protected int getCurrentPageNumber(object $query)

Returns the current page number for the list.

This will override the current page number provided by the user if it is past the last page of available records.

Parameters

object $query

protected string getPreferenceKey()

Returns a unique identifier for this widget and controller action for preference storage.

protected October\Rain\Database\Model getPreferenceStorage()

Specifies the model used for storing the user preferences.

protected Collection getRecords()

Returns all the records from the supplied model, after filtering.

protected array getSearchableColumns()

Returns a collection of columns which can be searched.

protected void getSetupListColumns()

Returns all the list columns used for list set up.

protected void getSetupPerPageOptions()

Returns an array of allowable records per page.

protected void getSortableColumns()

Returns a collection of columns which are sortable.

protected void getTotalColumns()

Calculates the total columns used in the list, including checkboxes and other additions.

protected boolean isColumnPivot(ListColumn $column)

Checks if a column refers to a pivot model specifically.

Parameters

ListColumn $column - List column object

protected boolean isColumnRelated(ListColumn $column, boolean $multi=false)

Check if column refers to a relation of the model

Parameters

ListColumn $column - List column object
boolean $multi - If set, returns true only if the relation is a "multiple relation type"

protected void isSortable($column=NULL)

Returns true if the column can be sorted.

Parameters

$column

protected void loadAssets()

Adds widget specific asset files. Use $this->addJs() and $this->addCss() to register new assets to include on the page.

protected void makeListColumn($name, $config)

Creates a list column object from it's name and configuration.

Parameters

$name
$config

protected string parseTableName(string $sql, string $table)

Replaces the @ symbol with a table name in a model

Parameters

string $sql
string $table

protected void validateDateTimeValue($value, $column)

Validates a column type as a date

Parameters

$value
$column

protected void validateModel()

Validate the supplied form model.

Show inherited protected methods

Inherited protected methods

protected void addAsset(string $type, string $path, array $attributes) - defined in Backend\Classes\WidgetBase. Adds the provided asset to the internal asset collections.
protected array emitterEventSortEvents(string $eventName) - defined in Backend\Classes\WidgetBase. Sort the listeners for a given event by priority.
protected boolean extendableIsAccessible(mixed $class, string $propertyName) - defined in October\Rain\Extension\Extendable. Checks if a property is accessible, property equivalent of is_callable().
protected void extensionExtractMethods(string $extensionName, object $extensionObject) - defined in October\Rain\Extension\Extendable. Extracts the available methods from a behavior and adds it to the.
protected void fillFromConfig(array $properties=NULL) - defined in Backend\Classes\WidgetBase. Transfers config values stored inside the $config property directly.
protected string getAssetEntryBuildPath(array $asset) - defined in Backend\Classes\WidgetBase. Internal helper, attaches a build code to an asset path.
protected string getAssetScheme(string $asset) - defined in Backend\Classes\WidgetBase. Internal helper, get asset scheme.
protected void getLocalPath($relativePath) - defined in Backend\Classes\WidgetBase.
protected string getSession(string $key=NULL, string $default=NULL) - defined in Backend\Classes\WidgetBase. Retrieves a widget related key/value pair from session data.
protected void handleViewException(Exception $e, int $obLevel) - defined in Backend\Classes\WidgetBase. Handle a view exception.
protected string makeSessionId() - defined in Backend\Classes\WidgetBase. Returns a unique session identifier for this widget and controller action.
protected void putSession(string $key, string $value) - defined in Backend\Classes\WidgetBase. Saves a widget related key/value pair in to session data.
protected void removeDuplicates() - defined in Backend\Classes\WidgetBase. Removes duplicate assets from the entire collection.

Backend

Behaviors

ImportExportController

Classes

Controllers

Database

Seeds

Facades

FormWidgets

Helpers

Exception

Models

ReportWidgets

Skins

Traits

Widgets

Table

Cms

Classes

Components

Contracts

Controllers

Facades

FormWidgets

Helpers

Models

ReportWidgets

Traits

Twig

Widgets

System

Behaviors

Classes

Console

Controllers

Database

Seeds

Helpers

Models

ReportWidgets

Traits

Twig

Events

backend

ajax

filter

form

list

menu

page

user

cms

ajax

block

combiner

component

object

page

router

template

theme

halcyon

datasource

db

mailer

media

file

folder

model

auth

form

relation

system

assets

console

mirror

theme

sync

reportwidgets

settings