1. Documentation
  2. API
  3. Backend
  4. Widgets
  5. Lists

Backend\Widgets\Lists

Overview

Lists Widget used for building back end lists, renders a list of model objects

Extends
Implements
  • October\Contracts\Element\ListElement

Public Properties

public array $columns

columns configuration.

public Model $model

model object for the list.

public string $recordUrl

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

public string $recordOnClick

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

public string $noRecordsMessage

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

public int $recordsPerPage

recordsPerPage as maximum rows to display.

public array $perPageOptions

perPageOptions is the number of items per page.

public bool $showSorting

showSorting options for each column.

public mixed $defaultSort

defaultSort column to look for.

public bool $showCheckboxes

showCheckboxes next to each record row.

public bool $showSetup

showSetup displays the list set up used for column visibility and ordering.

public bool $expandLastColumn

expandLastCol will expand to squeeze extra room from the last column.

public bool|string $showPagination

showPagination when limiting records per page.

public bool $showPageNumbers

showPageNumbers with pagination, disable to improve performance.

public string $customViewPath

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

public string $customPageName

customPageName specifies a name to use in the page URL for paginated records.

public array $cssClasses

cssClasses to apply to the list container element

Show inherited public properties

Inherited Public Properties

Protected Properties

protected $defaultAlias

defaultAlias to identify this widget.

protected array $allColumns

allColumns collection of all list columns used in this list.

See Also

protected array $columnOverride

columnOverride default columns with supplied key names.

protected array $visibleColumns

visibleColumns to display and their order.

protected object $records

records of models as a data collection.

protected int $currentPageNumber

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

sortDirection sets the list sorting direction (asc, desc)

protected string $sortStep

sortStep allows for indeterminate sorting

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 static array $preferenceCache

Cache for retrieved user preferences.

Show inherited protected properties

Inherited Protected Properties

Public Methods

public addColumns()

public addColumns(array $columns): void

addColumns programmatically add columns, used internally and for extensibility.

public addFilter()

public addFilter($filter): void

addFilter query to the stack.

public defineColumn()

public defineColumn(
    $columnName = null,
    $label = null
): October\Rain\Element\Lists\ColumnDefinition

defineColumn adds a column to the list element

public getColumn()

public getColumn(string $column): mixed

getColumn gets a specified column object

public getColumnValue()

public getColumnValue($record, $column): void

getColumnValue returns a column value, with filters applied

public getColumnValueRaw()

public getColumnValueRaw($record, $column): string

getColumnValueRaw returns a raw column value

public getColumns()

public getColumns(): array

getColumns gets all the registered columns for the instance.

public getHeaderTooltipValue()

public getHeaderTooltipValue($column): string

getHeaderTooltipValue looks up the column header

public getHeaderValue()

public getHeaderValue($column): void

getHeaderValue looks up the column header

public getModel()

public getModel(): Model|null

getModel returns the active model for this list.

public getRecordAction()

public getRecordAction($record): array|null

public getRecordOnClick()

public getRecordOnClick(Model $record): string

getRecordOnClick returns the onclick event for a list row.

public getRecordUrl()

public getRecordUrl(Model $record): string

getRecordUrl returns the record URL address for a list row.

public getRowClass()

public getRowClass(Model $record): string

getRowClass adds a custom CSS class string to a record row

public getSortColumn()

public getSortColumn(): void

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

public getSortDirection()

public getSortDirection(): void

getSortDirection returns the current sort direction or default of 'asc'

public getSortStep()

public getSortStep(): int

getSortStep returns the current indeterminate step

public getUserPreference()

public getUserPreference(
    string $key = null,
    mixed $default = null
): mixed

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

public getUserPreferences()

public getUserPreferences(): array

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

public getVisibleColumns()

public getVisibleColumns(): void

getVisibleColumns returns the list columns that are visible by list settings or default

public hasRecordAction()

public hasRecordAction(): bool

hasRecordAction will specify is anything is clickable

public init()

public init(): void

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

public isColumnVisible()

public isColumnVisible($columnName): bool

isColumnVisible checks if a column is visible to the list

public isUserSorting()

public isUserSorting(): bool

isUserSorting returns true if the user has requested a sort column

public onApplySetup()

public onApplySetup(): void

onApplySetup handler

public onFilter()

public onFilter(): void

onFilter event handler for changing the filter

public onLoadSetup()

public onLoadSetup(): void

onLoadSetup handler to display the list set up.

public onPaginate()

public onPaginate(): void

onPaginate event handler for switching the page number.

public onRefresh()

public onRefresh(): void

onRefresh event handler for refreshing the list.

public onResetSetup()

public onResetSetup(): void

onResetSetup handler

public onSort()

public onSort(): void

onSort AJAX handler for sorting the list.

public prepareQuery()

public prepareQuery(): void

prepareQuery applies any filters to the model

public prepareVars()

public prepareVars(): void

prepareVars for display

public putUserPreference()

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

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

public removeColumn()

public removeColumn(string $column): void

removeColumn programmatically removes a column, used for extensibility.

public render()

public render(): void

Renders the widget.

public resetUserPreference()

public resetUserPreference(string $key): void

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

public resetUserPreferences()

public resetUserPreferences(): void

Clears all user preferences for this controller/widget.

public setSearchOptions()

public setSearchOptions(array $options = []): void

setSearchOptions applies a search options to the list search.

public setSearchTerm()

public setSearchTerm(string $term, boolean $resetState = false): void

setSearchTerm applies a search term to the list results.

Show inherited public methods

Inherited Public Methods

Protected Methods

protected applySearchToQuery()

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

applySearchToQuery applies the search constraint to a query.

protected defineListColumns()

protected defineListColumns(): array

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

protected evalColorPickerTypeValue()

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

evalColorPickerTypeValue as background color, to be seen at list

protected evalCustomListType()

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

evalCustomListType processes a custom list types registered by plugins and the app.

protected evalDateTypeValue()

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

evalDateTypeValue as a date value

protected evalDatetimeTypeValue()

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

evalDatetimeTypeValue as a datetime value

protected evalImageTypeValue()

protected evalImageTypeValue($record, $column, $value): string

evalImageTypeValue will process an image value

protected evalLinkageTypeValue()

protected evalLinkageTypeValue($record, $column, $value): void

protected evalNumberTypeValue()

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

evalNumberTypeValue process as number, proxy to text but uses different styling

protected evalPartialTypeValue()

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

evalPartialTypeValue as partial reference

protected evalSelectableTypeValue()

protected evalSelectableTypeValue($record, $column, $value): void

evalSelectableTypeValue processes as selectable value types for 'dropdown', 'radio', 'balloon-selector' and similar form field types

protected evalSummaryTypeValue()

protected evalSummaryTypeValue($record, $column, $value): void

evalSummaryTypeValue will limit a value by words

protected evalSwitchTypeValue()

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

evalSwitchTypeValue as boolean switch

protected evalTextTypeValue()

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

evalTextTypeValue as text and escape the value

protected evalTimeTypeValue()

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

evalTimeTypeValue as a time value

protected evalTimesinceTypeValue()

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

evalTimesinceTypeValue as diff for humans (1 min ago)

protected evalTimetenseTypeValue()

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

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

protected getCheckedRows()

protected getCheckedRows(): array

protected getCheckedRowsEncoded()

protected getCheckedRowsEncoded(): string

protected getColumnTimezonePreference()

protected getColumnTimezonePreference($column, $default = true): bool

getColumnTimezonePreference for date specific columns

protected getCurrentPageNumber()

protected getCurrentPageNumber(object $query): int

getCurrentPageNumber 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.

protected getPaginationElements()

protected getPaginationElements($records): array

getPaginationElements get the array of elements to pass to the view.

protected getPreferenceKey()

protected getPreferenceKey(): string

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

protected getPreferenceStorage()

protected getPreferenceStorage(): October\Rain\Database\Model

Specifies the model used for storing the user preferences.

protected getRecords()

protected getRecords(): Collection

getRecords returns all the records from the supplied model, after filtering.

protected getSearchableColumns()

protected getSearchableColumns(): array

getSearchableColumns returns a collection of columns which can be searched.

protected getSetupListColumns()

protected getSetupListColumns(): void

getSetupListColumns returns all the list columns used for list set up.

protected getSetupPerPageOptions()

protected getSetupPerPageOptions(): void

Returns an array of allowable records per page.

protected getSortableColumns()

protected getSortableColumns(): void

getSortableColumns returns a collection of columns which are sortable.

protected getTotalColumns()

protected getTotalColumns(): void

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

protected isColumnPivot()

protected isColumnPivot($column): bool

isColumnPivot checks if a column refers to a pivot model specifically.

protected isColumnRelated()

protected isColumnRelated($column, $isMulti = false): bool

isColumnRelated checks if column refers to a relation of the model, with a toggle switch for checking only relationships with multiple records.

protected isColumnSortable()

protected isColumnSortable($columnName): bool

isColumnSortable checks if column can be sorted, excluding calculated non visible columns

protected isRowChecked()

protected isRowChecked($record): bool

protected isSortable()

protected isSortable($column = null): void

isSortable returns true if the column can be sorted.

protected loadAssets()

protected loadAssets(): void

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

protected makeListColumn()

protected makeListColumn($name, $config): void

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

protected parseTableName()

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

parseTableName replaces the @ symbol with a table name in a model

protected processAutoOrder()

protected processAutoOrder(&$columns): void

processAutoOrder applies a default sort order to all columns

protected processColumnTypeModifiers()

protected processColumnTypeModifiers(&$columns): void

protected processHiddenColumns()

protected processHiddenColumns($columns): void

processHiddenColumns purges hidden columns

protected processPermissionCheck()

protected processPermissionCheck($columns): void

processPermissionCheck check if user has permissions to show the column and removes it if permission is denied

protected processUserColumnOrders()

protected processUserColumnOrders(&$columns, $userPreference): void

processUserColumnOrders applies a supplied column order from a user preference

protected useSorting()

protected useSorting(): bool

protected validateDateTimeValue()

protected validateDateTimeValue($value, $column): void

validateDateTimeValue column type

protected validateModel()

protected validateModel(): void

validateModel is present and right class type

Show inherited protected methods

Inherited Protected Methods