ListModel

Extends BaseDatabaseModel Implements FormFactoryAwareInterface, ListModelInterface

Model class for handling lists of items.

since

1.6

package

Joomla CMS

Methods

__construct

Constructor

__construct(mixed||string|int config = [], \Joomla\CMS\MVC\Factory\MVCFactoryInterface factory = null) : 
since

1.6

throws

Exception

Arguments

config

array<string|int, mixed>An array of configuration options (name, state, dbo, table_path, ignore_request).

factory

MVCFactoryInterface|nullThe factory.

Response

mixed

__get

Proxy for _db variable.

__get( name) : 
inherited deprecated
since

4.2.0

deprecated

4.3 will be removed in 6.0 Use getDatabase() instead of directly accessing _db

Arguments

name

stringThe name of the element

Response

mixedThe value of the element if set, null otherwise

__toString

Magic method to convert the object to a string gracefully.

__toString() : 
inherited deprecated
since

1.7.0

deprecated

4.3 will be removed in 6.0 Classes should provide their own __toString() implementation.

Response

stringThe classname.

_createFileName

Create the filename for a resource

_createFileName( type, mixed||string|int parts = []) : 
inherited static deprecated
since

3.0

deprecated

4.3 will be removed in 6.0 Will be removed without replacement

Arguments

type

stringThe resource type to create the filename for.

parts

array<string|int, mixed>An associative array of filename information.

Response

stringThe filename

_createTable

Method to load and return a table object.

_createTable( name,  prefix = 'Table', mixed||string|int config = []) : \Joomla\CMS\Table\Table|bool
inherited
since

3.0

see JTable::getInstance()

Arguments

name

stringThe name of the view

prefix

stringThe class prefix. Optional.

config

array<string|int, mixed>Configuration settings to pass to Table::getInstance

Response

Table|boolTable object or boolean false if failed

_getList

Gets an array of objects from the results of database query.

_getList(\Joomla\Database\DatabaseQuery|string query,  limitstart,  limit) : object||string|int
inherited
since

3.0

throws

RuntimeException

Arguments

query

DatabaseQuery|stringThe query.

limitstart

intOffset.

limit

intThe number of records.

Response

array<string|int, object>An array of results.

_getListCount

Returns a record count for the query.

_getListCount(\Joomla\Database\DatabaseQuery|string query) : 
inherited

Note: Current implementation of this method assumes that getListQuery() returns a set of unique rows, thus it uses SELECT COUNT(*) to count the rows. In cases that getListQuery() uses DISTINCT then either this method must be overridden by a custom implementation at the derived Model Class or a GROUP BY clause should be used to make the set unique.

since

3.0

Arguments

query

DatabaseQuery|stringThe query.

Response

intNumber of rows for query.

_getListQuery

Method to cache the last query constructed.

_getListQuery() : \Joomla\Database\DatabaseQuery

This method ensures that the query is constructed only once for a given state of the model.

since

1.6

Response

DatabaseQueryA DatabaseQuery object

addIncludePath

Add a directory where \JModelLegacy should search for models. You may either pass a string or an array of directories.

addIncludePath( path = '',  prefix = '') : mixed||string|int
inherited static deprecated
since

3.0

deprecated

4.3 will be removed in 6.0 Will be removed without replacement. Get the model through the MVCFactory + namespace instead

see

Arguments

path

mixedA path or array[sting] of paths to search.

prefix

stringA prefix for models.

Response

array<string|int, mixed>An array with directory elements. If prefix is equal to '', all directories are returned.

addTablePath

Adds to the stack of model table paths in LIFO order.

addTablePath( path) : 
inherited static deprecated
since

3.0

deprecated

4.3 will be removed in 6.0 Will be removed without replacement. Get the model through the MVCFactory instead

Arguments

path

mixedThe directory as a string or directories as an array to add.

Response

void

bootComponent

Boots the component with the given name.

bootComponent( component) : \Joomla\CMS\Extension\ComponentInterface
inherited
since

4.0.0

Arguments

component

stringThe component name, eg. com_content.

Response

ComponentInterfaceThe service container

cleanCache

Clean the cache

cleanCache( group = null) : 
inherited
since

3.0

Arguments

group

stringThe cache group

Response

void

createModelFromComponent

Returns a Model object by loading the component from the prefix.

createModelFromComponent( type,  prefix = '', mixed||string|int config = []) : \Joomla\CMS\MVC\Model\ModelInterface|null
inherited static deprecated
since

4.0.0

deprecated

4.3 will be removed in 6.0 Will be removed without replacement

Arguments

type

stringThe model type to instantiate

prefix

stringPrefix for the model class name. Optional.

config

array<string|int, mixed>Configuration array for model. Optional.

Response

ModelInterface|nullA ModelInterface instance or null on failure

def

Sets a default value if not already assigned

def( property,  default = null) : 
inherited deprecated
since

1.7.0

deprecated

4.3.0 will be removed in 6.0 Defining dynamic properties should not be used anymore

Arguments

property

stringThe name of the property.

default

mixedThe default value.

Response

mixed

dispatchEvent

Dispatches the given event on the internal dispatcher, does a fallback to the global one.

dispatchEvent(\Joomla\Event\EventInterface event) : 
inherited deprecated
since

4.1.0

deprecated

4.4 will be removed in 6.0. Use $this->getDispatcher() directly.

Arguments

event

EventInterfaceThe event

Response

void

get

Returns a property of the object or the default value if the property is not set.

get( property,  default = null) : 
inherited deprecated
since

1.7.0

see CMSObject::getProperties()
deprecated

4.3.0 will be removed in 6.0 Create a proper getter function for the property

Arguments

property

stringThe name of the property.

default

mixedThe default value.

Response

mixedThe value of the property.

getActiveFilters

Function to get the active filters

getActiveFilters() : mixed||string|int
since

3.2

Response

array<string|int, mixed>Associative array in the format: array('filter_published' => 0)

getCacheControllerFactory

Get the CacheControllerFactoryInterface.

getCacheControllerFactory() : \Joomla\CMS\Cache\CacheControllerFactoryInterface
inherited
since

4.2.0

Response

CacheControllerFactoryInterface

getCurrentUser

Returns the current user, if none is set the identity of the global app is returned. This will change in 6.0 and an empty user will be returned.

getCurrentUser() : \Joomla\CMS\User\User
inherited
since

4.2.0

Response

User

getDbo

Get the database driver.

getDbo() : \Joomla\Database\DatabaseInterface
inherited deprecated
since

4.2.0

throws

UnexpectedValueException

deprecated

4.3 will be removed in 6.0 Use getDatabase() instead Example: $model->getDatabase();

Response

DatabaseInterfaceThe database driver.

getDispatcher

Get the event dispatcher.

getDispatcher() : \Joomla\Event\DispatcherInterface
inherited

The override was made to keep a backward compatibility for legacy component. TODO: Remove the override in 6.0

since

4.4.0

throws

UnexpectedValueExceptionMay be thrown if the dispatcher has not been set.

Response

DispatcherInterface

getEmptyStateQuery

Provide a query to be used to evaluate if this is an Empty State, can be overridden in the model to provide granular control.

getEmptyStateQuery() : \Joomla\Database\DatabaseQuery
since

4.0.0

Response

DatabaseQuery

getError

Get the most recent error message.

getError( i = null,  toString = true) : 
inherited deprecated
since

1.7.0

deprecated

3.1.4 will be removed in 6.0 Will be removed without replacement Catch thrown Exceptions instead of getError

Arguments

i

intOption error index.

toString

boolIndicates if Exception objects should return their error message.

Response

stringError message

getErrors

Return all errors, if any.

getErrors() : mixed||string|int
inherited deprecated
since

1.7.0

deprecated

3.1.4 will be removed in 6.0 Will be removed without replacement Catch thrown Exceptions instead of getErrors

Response

array<string|int, mixed>Array of error messages.

getFilterForm

Get the filter form

getFilterForm(mixed||string|int data = [],  loadData = true) : \Joomla\CMS\Form\Form|null
since

3.2

Arguments

data

array<string|int, mixed>data

loadData

boolload current data

Response

Form|nullThe \JForm object or null if the form can't be found

getFormFactory

Get the FormFactoryInterface.

getFormFactory() : \Joomla\CMS\Form\FormFactoryInterface
inherited abstract
since

4.0.0

throws

UnexpectedValueExceptionMay be thrown if the FormFactory has not been set.

Response

FormFactoryInterface

getInstance

Returns a Model object, always creating it

getInstance( type,  prefix = '', mixed||string|int config = []) : self|bool
inherited static deprecated
since

3.0

deprecated

4.3 will be removed in 6.0 Will be removed without replacement. Get the model through the MVCFactory instead Example: Factory::getApplication->bootComponent('com_xxx')->getMVCFactory()->createModel($type, $prefix, $config);

Arguments

type

stringThe model type to instantiate

prefix

stringPrefix for the model class name. Optional.

config

array<string|int, mixed>Configuration array for model. Optional.

Response

self|boolA \JModelLegacy instance or false on failure

getIsEmptyState

Is this an empty state, I.e: no items of this type regardless of the searched for states.

getIsEmptyState() : 
throws

Exception

since

4.0.0

Response

bool

getItems

Method to get an array of data items.

getItems() : 
since

1.6

Response

mixedAn array of data items on success, false on failure.

getListQuery

Method to get a DatabaseQuery object for retrieving the data set from a database.

getListQuery() : \Joomla\Database\DatabaseQuery|string
since

1.6

Response

DatabaseQuery|stringA DatabaseQuery object to retrieve the data set.

getMVCFactory

Returns the MVC factory.

getMVCFactory() : \Joomla\CMS\MVC\Factory\MVCFactoryInterface
inherited
since

4.0.0

throws

UnexpectedValueException

Response

MVCFactoryInterface

getName

Method to get the model name

getName() : 
inherited

The model name. By default parsed using the classname or it can be set by passing a $config['name'] in the class constructor

since

4.0.0

throws

Exception

Response

stringThe name of the model

getPagination

Method to get a \JPagination object for the data set.

getPagination() : \Joomla\CMS\Pagination\Pagination
since

1.6

Response

PaginationA Pagination object for the data set.

getProperties

Returns an associative array of object properties.

getProperties( public = true) : mixed||string|int
inherited deprecated
since

1.7.0

see CMSObject::get()
deprecated

4.3.0 will be removed in 6.0 Create a proper getter function for the property

Arguments

public

boolIf true, returns only the public properties.

Response

array<string|int, mixed>

getStart

Method to get the starting number of items for the data set.

getStart() : 
since

1.6

Response

intThe starting number of items available in the data set.

getState

Method to get state variables.

getState( property = null,  default = null) : 
inherited
since

4.0.0

Arguments

property

stringOptional parameter name

default

mixedOptional default value

Response

mixedThe property where specified, the state object where omitted

getStoreId

Method to get a store id based on the model configuration state.

getStoreId( id = '') : 

This is necessary because the model is used by the component and different modules that might need different sets of data or different ordering requirements.

since

1.6

Arguments

id

stringAn identifier string to generate the store id.

Response

stringA store id.

getTable

Method to get a table object, load it if necessary.

getTable( name = '',  prefix = '', mixed||string|int options = []) : \Joomla\CMS\Table\Table
inherited
since

3.0

throws

Exception

Arguments

name

stringThe table name. Optional.

prefix

stringThe class prefix. Optional.

options

array<string|int, mixed>Configuration array for model. Optional.

Response

TableA Table object

getTotal

Method to get the total number of items for the data set.

getTotal() : 
since

1.6

Response

intThe total number of items available in the data set.

getUserStateFromRequest

Gets the value of a user state variable and sets it in the session

getUserStateFromRequest( key,  request,  default = null,  type = 'none',  resetPage = true) : 

This is the same as the method in Application except that this also can optionally force you back to the first page when a filter has changed

since

1.6

Arguments

key

stringThe key of the user state variable.

request

stringThe name of the variable passed in a request.

default

stringThe default value for the variable if not found. Optional.

type

stringFilter for the variable, for valid values see {@link InputFilter::clean()}. Optional.

resetPage

boolIf true, the limitstart in request is set to zero

Response

mixedThe request user state.

isCheckedOut

Method to check if the given record is checked out by the current user

isCheckedOut(\stdClass item) : 
inherited

Arguments

item

stdClassThe record to check

Response

bool

loadForm

Method to get a form object.

loadForm( name,  source = null, mixed||string|int options = [],  clear = false,  xpath = null) : \Joomla\CMS\Form\Form
inherited
see Form
since

4.0.0

throws

Exception

Arguments

name

stringThe name of the form.

source

stringThe form source. Can be XML string if file flag is set to false.

options

array<string|int, mixed>Optional array of options for the form creation.

clear

boolOptional argument to force load a new form.

xpath

stringAn optional xpath to search for the fields.

Response

Form

loadFormData

Method to get the data that should be injected in the form.

loadFormData() : 
since

3.2

Response

mixedThe data for the form.

populateState

Method to auto-populate the model state.

populateState( ordering = null,  direction = null) : 

This method should only be called once per instantiation and is designed to be called on the first call to the getState() method unless the model configuration flag to ignore the request is set.

Note. Calling getState in this method will result in recursion.

since

1.6

Arguments

ordering

stringAn optional ordering field.

direction

stringAn optional direction (asc|desc).

Response

void

preprocessData

Method to allow derived classes to preprocess the data.

preprocessData( context,  &data,  group = 'content') : 
inherited
since

4.0.0

Arguments

context

stringThe context identifier.

data

mixedThe data to be processed. It gets altered directly.

group

stringThe name of the plugin group to import (defaults to "content").

Response

void

preprocessForm

Method to allow derived classes to preprocess the form.

preprocessForm(\Joomla\CMS\Form\Form form,  data,  group = 'content') : 
inherited
see FormField
since

4.0.0

throws

Exceptionif there is an error in the form event.

Arguments

form

FormA Form object.

data

mixedThe data expected for the form.

group

stringThe name of the plugin group to import (defaults to "content").

Response

void

refineSearchStringToRegex

Parse and transform the search string into a string fit for regex-ing arbitrary strings against

refineSearchStringToRegex( search,  regexDelimiter = '/') : 
since

3.4

Arguments

search

stringThe search string

regexDelimiter

stringThe regex delimiter to use for the quoting

Response

stringSearch string escaped for regex

set

Modifies a property of the object, creating it if it does not already exist.

set( property,  value = null) : 
inherited deprecated
since

1.7.0

deprecated

4.3.0 will be removed in 6.0 Create a proper setter function for the property

Arguments

property

stringThe name of the property.

value

mixedThe value of the property to set.

Response

mixedPrevious value of the property.

setCacheControllerFactory

Set the cache controller factory to use.

setCacheControllerFactory(\Joomla\CMS\Cache\CacheControllerFactoryInterface cacheControllerFactory = null) : 
inherited
since

4.2.0

Arguments

cacheControllerFactory

CacheControllerFactoryInterfaceThe cache controller factory to use.

Response

void

setCurrentUser

Sets the current user.

setCurrentUser(\Joomla\CMS\User\User currentUser) : 
inherited
since

4.2.0

Arguments

currentUser

UserThe current user object

Response

void

setDbo

Set the database driver.

setDbo(\Joomla\Database\DatabaseInterface db = null) : 
inherited deprecated
since

4.2.0

deprecated

4.3 will be removed in 6.0 Use setDatabase() instead Example: $model->setDatabase($db);

Arguments

db

DatabaseInterface|nullThe database driver.

Response

void

setError

Add an error message.

setError( error) : 
inherited deprecated
since

1.7.0

deprecated

3.1.4 will be removed in 6.0 Will be removed without replacement Throw an Exception instead of using setError

Arguments

error

stringError message.

Response

void

setFormFactory

Set the form factory to use.

setFormFactory(\Joomla\CMS\Form\FormFactoryInterface formFactory = null) : 
inherited
since

4.0.0

Arguments

formFactory

FormFactoryInterface|nullThe form factory to use.

Response

$this

setMVCFactory

Set the MVC factory.

setMVCFactory(\Joomla\CMS\MVC\Factory\MVCFactoryInterface mvcFactory) : 
inherited
since

4.0.0

Arguments

mvcFactory

MVCFactoryInterfaceThe MVC factory

Response

void

setProperties

Set the object properties based on a named array/hash.

setProperties( properties) : 
inherited deprecated
since

1.7.0

see CMSObject::set()
deprecated

4.3.0 will be removed in 6.0 Create a proper setter function for the property

Arguments

properties

mixedEither an associative array or another object.

Response

bool

setState

Method to set state variables.

setState( property,  value = null) : 
inherited
since

4.0.0

Arguments

property

stringThe name of the property

value

mixedThe value of the property to set or null

Response

mixedThe previous value of the property or null if not set

Properties

_errors

An array of error messages or Exception objects.

inherited deprecated
since

1.7.0

deprecated

3.1.4 JError has been deprecated

Type(s)

array<string|int, mixed>

__state_set

Indicates if the internal state has been set

inherited
since

4.0.0

Type(s)

bool

state

A state object

inherited
since

4.0.0

Type(s)

CMSObject

name

The model (base) name

inherited
since

4.0.0

Type(s)

string

paths

The include paths

inherited static
since

4.0.0

Type(s)

array<string|int, mixed>

cacheControllerFactory

CacheControllerFactoryInterface

inherited
since

4.2.0

Type(s)

CacheControllerFactoryInterface

currentUser

The current user object.

inherited
since

4.2.0

Type(s)

User

mvcFactory

The mvc factory.

inherited
since

4.0.0

Type(s)

MVCFactoryInterface

option

The URL option for the component.

inherited
since

3.0

Type(s)

string

event_clean_cache

The event to trigger when cleaning cache.

inherited
since

3.0

Type(s)

string

formFactory

FormFactoryInterface

inherited
since

4.0.0

Type(s)

FormFactoryInterface

_forms

Array of form objects.

inherited
since

4.0.0

Type(s)

array<string|int, Form>

cache

Internal memory based cache array of data.

since

1.6

Type(s)

array<string|int, mixed>

context

Context string for the model type. This is used to handle uniqueness when dealing with the getStoreId() method and caching data structures.

since

1.6

Type(s)

string

filter_fields

Valid filter fields or ordering.

since

1.6

Type(s)

array<string|int, mixed>

query

An internal cache for the last query used.

since

1.6

Type(s)

DatabaseQuery|string

lastQueryStoreId

The cache ID used when last populating $this->query

since

3.10.4

Type(s)

null|string

filterFormName

Name of the filter form to load

since

3.2

Type(s)

string

htmlFormName

Associated HTML form

since

3.2

Type(s)

string

filterBlacklist

A list of filter variables to not merge into the model's state

deprecated
since

3.4.5

deprecated

4.0 will be removed in 6.0 Use $filterForbiddenList instead

Type(s)

array<string|int, mixed>

filterForbiddenList

A list of forbidden filter variables to not merge into the model's state

since

4.0.0

Type(s)

array<string|int, mixed>

listBlacklist

A list of forbidden variables to not merge into the model's state

deprecated
since

3.4.5

deprecated

4.0 will be removed in 6.0 Use $listForbiddenList instead

Type(s)

array<string|int, mixed>

listForbiddenList

A list of forbidden variables to not merge into the model's state

since

4.0.0

Type(s)

array<string|int, mixed>