FieldList
class FieldList extends ArrayList (View source)
A list designed to hold form field instances.
Traits
Allows an object to have extensions applied to it.
A class that can be instantiated or replaced via DI
Provides extensions to this object to integrate it with standard config API methods.
Allows an object to declare a set of custom methods
Config options
| extensions | array | An array of extension names and parameters to be applied to this object upon construction. |
from Extensible |
| unextendable_classes | array | Classes that cannot be extended |
from Extensible |
| casting | array | An array of objects to cast certain fields to. This is set up as an array in the format: |
from ViewableData |
| default_cast | string | The default object to cast scalar fields to if casting information is not specified, and casting to an object is required. |
from ViewableData |
| casting_cache | array | from ViewableData |
Properties
| protected static | array | $extra_methods | Custom method sources |
from CustomMethods |
| protected | array | $extra_method_registers | Name of methods to invoke by defineMethods for this instance |
from CustomMethods |
| protected static | array | $built_in_methods | Non-custom methods |
from CustomMethods |
| protected | Extension[] | $extension_instances | from Extensible | |
| protected | callable[][] | $beforeExtendCallbacks | List of callbacks to call prior to extensions having extend called on them, each grouped by methodName. |
from Extensible |
| protected | callable[][] | $afterExtendCallbacks | List of callbacks to call after extensions having extend called on them, each grouped by methodName. |
from Extensible |
| protected | ViewableData | $failover | A failover object to attempt to get data from if it is not present on this object. |
from ViewableData |
| protected | ViewableData | $customisedObject | from ViewableData | |
| protected | array | $items | Holds the items in the list |
from ArrayList |
| protected | string | $dataClass | Underlying type class for this list |
from ArrayList |
| protected | FormField[] | $sequentialSet | Cached flat representation of all fields in this set, including fields nested in CompositeFields. |
|
| protected | FormField[] | $sequentialSaveableSet | ||
| protected | CompositeField | $containerField | If this fieldlist is owned by a parent field (e.g. CompositeField) this is the parent field. |
Methods
Attempts to locate and call a method dynamically added to a class at runtime if a default cannot be located
Adds any methods from Extension instances attached to this object.
Register an callback to invoke that defines extra methods
Return TRUE if a method exists on this object
Get meta-data details on a named method
Return the names of all the methods available on this object
Add all the methods from an object property (which is an Extension) to this object.
Add all the methods from an object property (which is an Extension) to this object.
Add a wrapper method - a method which points to another method with a different name. For example, Thumbnail(x) can be wrapped to generateThumbnail(x)
Add callback as a method.
Allows user code to hook into Object::extend prior to control being delegated to extensions. Each callback will be reset once called.
Allows user code to hook into Object::extend after control being delegated to extensions. Each callback will be reset once called.
Adds any methods from Extension instances attached to this object.
Add an extension to a specific class.
No description
Get extra config sources for this class
Return TRUE if a class has a specified extension.
Calls a method if available on both this object and all applied Extensions, and then attempts to merge all results into an array
Run the given function on all of this object's extensions. Note that this method originally returned void, so if you wanted to return results, you're hosed
Get an extension instance attached to this object by name.
Returns TRUE if this object instance has a specific extension applied in $extension_instances. Extension instances are initialized at constructor time, meaning if you use add_extension() afterwards, the added extension will just be added to new instances of the extended class. Use the static method has_extension() to check if a class (not an instance) has a specific extension.
Get all extension instances for this specific object instance.
An implementation of the factory method, allows you to create an instance of a class
Creates a class instance by the "singleton" design pattern.
Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).
Gets the uninherited value for the given config option
Check if a field exists on this object or its failover.
Get the value of a property/field on this object. This will check if a method called get{$property} exists, then check if a field is available using ViewableData::getField(), then fall back on a failover object.
Set a property/field on this object. This will check for the existence of a method called set{$property}, then use the ViewableData::setField() method.
Set a failover object to attempt to get data from if it is not present on this object.
Check if a field exists on this object. This should be overloaded in child classes.
Get the value of a field on this object. This should be overloaded in child classes.
Set a field on this object. This should be overloaded in child classes.
Merge some arbitrary data in with this object. This method returns a ViewableData_Customised instance with references to both this and the new custom data.
Return the "casting helper" (a piece of PHP code that when evaluated creates a casted value object) for a field on this object. This helper will be a subclass of DBField.
Get the class name a field on this object will be casted to.
Return the string-format type for the given field.
Render this object into the template, and get the result as a string. You can pass one of the following as the $template parameter:
- a template name (e.g. Page)
- an array of possible template names - the first valid one will be used
- an SSViewer instance
Generate the cache name for a field
Store a value in the field cache
Get the value of a field on this object, automatically inserting the value into any available casting objects that have been specified.
A simple wrapper around ViewableData::obj() that automatically caches the result so it can be used again without re-running the method.
Checks if a given method/field has a valid value. If the result is an object, this will return the result of the exists method, otherwise will check if the result is not just an empty paragraph tag.
Get the string value of a field on this object that has been suitable escaped to be inserted directly into a template.
Get an array of XML-escaped values by field name
Find appropriate templates for SSViewer to use to render this object
When rendering some objects it is necessary to iterate over the object being rendered, to do this, you need access to itself.
Get part of the current classes ancestry to be used as a CSS class.
Return debug information about this object that can be rendered into a template
Return the class of items in this list, by looking at the first item inside it.
Return an array of the actual items that this ArrayList contains.
Return this list as an array and every object it as an sub array as well
Get a sub-range of this dataobjectset as an array Pass null to "remove the limit" - this is for consistency with DataList::limit(null) which itself will call SQLSelect::setLimit(null)
Replaces an item in this list with another item.
Merges with another array or list by pushing all the items in it onto the end of this list.
Removes items from this list which have a duplicate value for a certain field. This is especially useful when combining lists.
Pops the last element off the end of the list and returns it.
Push a single field onto the beginning of this FieldList instance.
Shifts the item off the beginning of the list and returns it.
Returns a map of this list
Find the first item of this list where the given key = value
Returns an array of a single field value for all items in the list.
Returns a unique array of a single field value for all the items in the list
Parses a specified column into a sort field and direction
Sorts this list by one or more fields. You can either pass in a single field name and direction, or a map of field names to sort directions.
Returns true if the given column can be used to filter the records.
Return a copy of this list which contains items matching any of these characteristics.
Take the "standard" arguments that the filter/exclude functions take and return a single array with 'colum' => 'value'
Extracts a value from an item in the list, where the item is either an object or array.
Return a sequential set of all fields that have data. This excludes wrapper composite fields as well as heading / help text fields.
Add an extra field to a tab within this FieldList.
Add a number of extra fields to a tab within this FieldList.
Remove the given field from the given tab in the field.
Removes a number of fields from a Tab/TabSet within this FieldList.
Remove a field or fields from this FieldList by Name.
Replace a single field with another. Ignores dataless fields such as Tabs and TabSets
Rename the title of a particular field name in this set.
Returns the specified tab object, creating it if necessary.
Inserts a field before a particular field in a FieldList.
Inserts a field after a particular field in a FieldList.
Handler method called before the FieldList is going to be manipulated.
Return all fields in a form - including fields nested in CompositeFields.
Transform this FieldList with a given transform method, e.g. $this->transform(new ReadonlyTransformation())
Change the order of fields in this FieldList by specifying an ordered list of field names.
Find the numerical position of a field within the children collection. Doesn't work recursively.
Default template rendering of a FieldList will concatenate all FieldHolder values.
Details
mixed
__call(string $method, array $arguments)
Attempts to locate and call a method dynamically added to a class at runtime if a default cannot be located
You can add extra methods to a class using Extensions}, {@link Object::createMethod() or Object::addWrapperMethod()
protected
defineMethods()
Adds any methods from Extension instances attached to this object.
All these methods can then be called directly on the instance (transparently mapped through __call()}), or called explicitly through {@link extend().
protected
registerExtraMethodCallback(string $name, callable $callback)
Register an callback to invoke that defines extra methods
bool
hasMethod(string $method)
Return TRUE if a method exists on this object
This should be used rather than PHP's inbuild method_exists() as it takes into account methods added via extensions
protected array
getExtraMethodConfig(string $method)
Get meta-data details on a named method
array
allMethodNames(bool $custom = false)
Return the names of all the methods available on this object
protected array
findMethodsFromExtension(object $extension)
deprecated
deprecated
No description
protected
addMethodsFrom(string $property, string|int $index = null)
Add all the methods from an object property (which is an Extension) to this object.
protected
removeMethodsFrom(string $property, string|int $index = null)
Add all the methods from an object property (which is an Extension) to this object.
protected
addWrapperMethod(string $method, string $wrap)
Add a wrapper method - a method which points to another method with a different name. For example, Thumbnail(x) can be wrapped to generateThumbnail(x)
protected
addCallbackMethod(string $method, callable $callback)
Add callback as a method.
protected
beforeExtending(string $method, callable $callback)
Allows user code to hook into Object::extend prior to control being delegated to extensions. Each callback will be reset once called.
protected
afterExtending(string $method, callable $callback)
Allows user code to hook into Object::extend after control being delegated to extensions. Each callback will be reset once called.
protected
constructExtensions()
deprecated
deprecated
No description
protected
defineExtensionMethods()
Adds any methods from Extension instances attached to this object.
All these methods can then be called directly on the instance (transparently mapped through __call()}), or called explicitly through {@link extend().
static bool
add_extension(string $classOrExtension, string $extension = null)
Add an extension to a specific class.
The preferred method for adding extensions is through YAML config, since it avoids autoloading the class, and is easier to override in more specific configurations.
As an alternative, extensions can be added to a specific class directly in the Object::$extensions array. See SiteTree::$extensions for examples. Keep in mind that the extension will only be applied to new instances, not existing ones (including all instances created through singleton()).
static
remove_extension(string $extension)
Remove an extension from a class.
Note: This will not remove extensions from parent classes, and must be called directly on the class assigned the extension.
Keep in mind that this won't revert any datamodel additions of the extension at runtime, unless its used before the schema building kicks in (in your _config.php). Doesn't remove the extension from any Object instances which are already created, but will have an effect on new extensions. Clears any previously created singletons through singleton() to avoid side-effects from stale extension information.
static array
get_extensions(string $class = null, bool $includeArgumentString = false)
No description
static array|null
get_extra_config_sources(string $class = null)
Get extra config sources for this class
static bool
has_extension(string $classOrExtension, string $requiredExtension = null, bool $strict = false)
Return TRUE if a class has a specified extension.
This supports backwards-compatible format (static Object::has_extension($requiredExtension)) and new format ($object->has_extension($class, $requiredExtension))
array
invokeWithExtensions(string $method, mixed $a1 = null, mixed $a2 = null, mixed $a3 = null, mixed $a4 = null, mixed $a5 = null, mixed $a6 = null, mixed $a7 = null)
Calls a method if available on both this object and all applied Extensions, and then attempts to merge all results into an array
array
extend(string $method, mixed $a1 = null, mixed $a2 = null, mixed $a3 = null, mixed $a4 = null, mixed $a5 = null, mixed $a6 = null, mixed $a7 = null)
Run the given function on all of this object's extensions. Note that this method originally returned void, so if you wanted to return results, you're hosed
Currently returns an array, with an index resulting every time the function is called. Only adds returns if they're not NULL, to avoid bogus results from methods just defined on the parent extension. This is important for permission-checks through extend, as they use min() to determine if any of the returns is FALSE. As min() doesn't do type checking, an included NULL return would fail the permission checks.
The extension methods are defined during __construct()} in {@link defineMethods().
Extension|null
getExtensionInstance(string $extension)
Get an extension instance attached to this object by name.
bool
hasExtension(string $extension)
Returns TRUE if this object instance has a specific extension applied in $extension_instances. Extension instances are initialized at constructor time, meaning if you use add_extension() afterwards, the added extension will just be added to new instances of the extended class. Use the static method has_extension() to check if a class (not an instance) has a specific extension.
Caution: Don't use singleton(
Extension[]
getExtensionInstances()
Get all extension instances for this specific object instance.
See get_extensions() to get all applied extension classes for this class (not the instance).
This method also provides lazy-population of the extension_instances property.
static Injectable
create(mixed ...$args)
An implementation of the factory method, allows you to create an instance of a class
This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.
This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create(SiteTree::class); $list = SiteTree::get();
static Injectable
singleton(string $class = null)
Creates a class instance by the "singleton" design pattern.
It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).
static Config_ForClass
config()
Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).
mixed
stat(string $name)
deprecated
deprecated
Get inherited config value
mixed
uninherited(string $name)
Gets the uninherited value for the given config option
$this
set_stat(string $name, mixed $value)
deprecated
deprecated
Update the config value for a given property
__construct(array $items = [])
No description
bool
__isset(string $property)
Check if a field exists on this object or its failover.
Note that, unlike the core isset() implementation, this will return true if the property is defined and set to null.
mixed
__get(string $property)
Get the value of a property/field on this object. This will check if a method called get{$property} exists, then check if a field is available using ViewableData::getField(), then fall back on a failover object.
__set(string $property, mixed $value)
Set a property/field on this object. This will check for the existence of a method called set{$property}, then use the ViewableData::setField() method.
setFailover(ViewableData $failover)
Set a failover object to attempt to get data from if it is not present on this object.
ViewableData|null
getFailover()
Get the current failover object if set
bool
hasField(string $field)
Check if a field exists on this object. This should be overloaded in child classes.
mixed
getField(string $field)
Get the value of a field on this object. This should be overloaded in child classes.
$this
setField(string $field, mixed $value)
Set a field on this object. This should be overloaded in child classes.
ViewableData_Customised
customise(array|ViewableData $data)
Merge some arbitrary data in with this object. This method returns a ViewableData_Customised instance with references to both this and the new custom data.
Note that any fields you specify will take precedence over the fields on this object.
bool
exists()
Returns true if this list has items
string
__toString()
No description
ViewableData
getCustomisedObj()
No description
setCustomisedObj(ViewableData $object)
No description
string
castingHelper(string $field)
Return the "casting helper" (a piece of PHP code that when evaluated creates a casted value object) for a field on this object. This helper will be a subclass of DBField.
string
castingClass(string $field)
Get the class name a field on this object will be casted to.
string
escapeTypeForField(string $field)
Return the string-format type for the given field.
DBHTMLText
renderWith(string|array|SSViewer $template, array $customFields = null)
Render this object into the template, and get the result as a string. You can pass one of the following as the $template parameter:
- a template name (e.g. Page)
- an array of possible template names - the first valid one will be used
- an SSViewer instance
protected string
objCacheName(string $fieldName, array $arguments)
Generate the cache name for a field
protected mixed
objCacheGet(string $key)
Get a cached value from the field cache
protected $this
objCacheSet(string $key, mixed $value)
Store a value in the field cache
protected $this
objCacheClear()
Clear object cache
object|DBField
obj(string $fieldName, array $arguments = [], bool $cache = false, string $cacheName = null)
Get the value of a field on this object, automatically inserting the value into any available casting objects that have been specified.
object|DBField
cachedCall(string $field, array $arguments = [], string $identifier = null)
A simple wrapper around ViewableData::obj() that automatically caches the result so it can be used again without re-running the method.
bool
hasValue(string $field, array $arguments = [], bool $cache = true)
Checks if a given method/field has a valid value. If the result is an object, this will return the result of the exists method, otherwise will check if the result is not just an empty paragraph tag.
string
XML_val(string $field, array $arguments = [], bool $cache = false)
Get the string value of a field on this object that has been suitable escaped to be inserted directly into a template.
array
getXMLValues(array $fields)
Get an array of XML-escaped values by field name
FormField[]
getIterator()
No description
array
getViewerTemplates(string $suffix = '')
Find appropriate templates for SSViewer to use to render this object
ViewableData
Me()
When rendering some objects it is necessary to iterate over the object being rendered, to do this, you need access to itself.
string
ThemeDir()
deprecated
deprecated
Return the directory if the current active theme (relative to the site root).
This method is useful for things such as accessing theme images from your template without hardcoding the theme
page - e.g. 
.
This method should only be used when a theme is currently active. However, it will fall over to the current project directory.
string
CSSClasses(string $stopAtClass = self::class)
Get part of the current classes ancestry to be used as a CSS class.
This method returns an escaped string of CSS classes representing the current classes ancestry until it hits a stop point - e.g. "Page DataObject ViewableData".
ViewableData_Debugger
Debug()
Return debug information about this object that can be rendered into a template
string
dataClass()
Return the class of items in this list, by looking at the first item inside it.
$this
setDataClass(string $class)
Hint this list to a specific type
int
count()
Return the number of items in this list
array
toArray()
Return an array of the actual items that this ArrayList contains.
$this
each(callable $callback)
Walks the list using the specified callback
debug()
No description
array
toNestedArray()
Return this list as an array and every object it as an sub array as well
Limitable
limit(int|null $length, int $offset = 0)
Get a sub-range of this dataobjectset as an array Pass null to "remove the limit" - this is for consistency with DataList::limit(null) which itself will call SQLSelect::setLimit(null)
add(mixed $item)
Add this $item into this list
remove(mixed $item)
Remove this item from this list
void
replace(array|object $item, array|object $with)
Replaces an item in this list with another item.
merge(array|object $with)
Merges with another array or list by pushing all the items in it onto the end of this list.
$this
removeDuplicates(string $field = 'ID')
Removes items from this list which have a duplicate value for a certain field. This is especially useful when combining lists.
push(array|object $item)
Push a single field onto the end of this FieldList instance.
array|object
pop()
Pops the last element off the end of the list and returns it.
unshift(array|object $item)
Push a single field onto the beginning of this FieldList instance.
array|object
shift()
Shifts the item off the beginning of the list and returns it.
mixed
first()
Returns the first item in the list
mixed
last()
Returns the last item in the list
Map
map(string $keyfield = 'ID', string $titlefield = 'Title')
Returns a map of this list
mixed
find(string $key, mixed $value)
Find the first item of this list where the given key = value
array
column(string $colName = 'ID')
Returns an array of a single field value for all items in the list.
array
columnUnique(string $colName = 'ID')
Returns a unique array of a single field value for all the items in the list
bool
canSortBy(string $by)
You can always sort a ArrayList
Sortable
reverse()
Reverses an ArrayList
protected array
parseSortColumn(string $column, mixed $direction = null)
Parses a specified column into a sort field and direction
Sortable
sort()
Sorts this list by one or more fields. You can either pass in a single field name and direction, or a map of field names to sort directions.
Note that columns may be double quoted as per ANSI sql standard
$this
shuffle()
Shuffle the items in this array list
bool
canFilterBy(string $by)
Returns true if the given column can be used to filter the records.
It works by checking the fields available in the first record of the list.
Filterable
filter()
Filter the list to include items with these characteristics
Filterable
filterAny()
Return a copy of this list which contains items matching any of these characteristics.
protected array
normaliseFilterArgs($column, $value = null)
Take the "standard" arguments that the filter/exclude functions take and return a single array with 'colum' => 'value'
SS_List
byIDs(array $ids)
Filter this list to only contain the given Primary IDs
mixed
byID(int $id)
Return the first item with the given ID
Filterable
filterByCallback(callable $callback)
No description
Filterable
exclude()
Exclude the list to not contain items with these characteristics
protected
shouldExclude($item, $args)
No description
bool
offsetExists(mixed $offset)
Returns whether an item with $key exists
DataObject
offsetGet(mixed $offset)
Returns item stored in list with index $key
offsetSet(mixed $offset, mixed $value)
Set an item with the key in $key
offsetUnset(mixed $offset)
Unset an item with the key in $key
protected mixed
extractValue(array|object $item, string $key)
Extracts a value from an item in the list, where the item is either an object or array.
__clone()
No description
recursiveWalk(callable $callback)
Iterate over each field in the current list recursively
FieldList
flattenFields()
Return a flattened list of all fields
FormField[]
dataFields()
Return a sequential set of all fields that have data. This excludes wrapper composite fields as well as heading / help text fields.
FormField[]
saveableFields()
No description
array
dataFieldNames()
Return array of all field names
protected
fieldNameError(FormField $field, $functionName)
Trigger an error for duplicate field names
protected
flushFieldsCache()
No description
protected
collateDataFields($list, bool $saveableOnly = false)
deprecated
deprecated
No description
$this
addFieldToTab(string $tabName, FormField $field, string $insertBefore = null)
Add an extra field to a tab within this FieldList.
This is most commonly used when overloading getCMSFields()
$this
addFieldsToTab(string $tabName, array $fields, string $insertBefore = null)
Add a number of extra fields to a tab within this FieldList.
This is most commonly used when overloading getCMSFields()
$this
removeFieldFromTab(string $tabName, string $fieldName)
Remove the given field from the given tab in the field.
$this
removeFieldsFromTab(string $tabName, array $fields)
Removes a number of fields from a Tab/TabSet within this FieldList.
$this
removeByName(string|array $fieldName, bool $dataFieldOnly = false)
Remove a field or fields from this FieldList by Name.
The field could also be inside a CompositeField.
bool
replaceField(string $fieldName, FormField $newField, bool $dataFieldOnly = true)
Replace a single field with another. Ignores dataless fields such as Tabs and TabSets
bool
renameField(string $fieldName, string $newFieldTitle)
Rename the title of a particular field name in this set.
bool
hasTabSet()
No description
Tab|null
findTab(string $tabName)
Returns the specified tab object, if it exists
Tab
findOrMakeTab(string $tabName, string $title = null)
Returns the specified tab object, creating it if necessary.
FormField|null
fieldByName(string $name)
Returns a named field.
You can use dot syntax to get fields from child composite fields
FormField|null
dataFieldByName(string $name)
Returns a named field in a sequential set.
Use this if you're using nested FormFields.
FormField|false
insertBefore(string $name, FormField $item, bool $appendIfMissing = true)
Inserts a field before a particular field in a FieldList.
Will traverse CompositeFields depth-first to find the matching $name, and insert before the first match
FormField|false
insertAfter(string $name, FormField $item, bool $appendIfMissing = true)
Inserts a field after a particular field in a FieldList.
Will traverse CompositeFields depth-first to find the matching $name, and insert after the first match
protected
onBeforeInsert(FormField $item)
Handler method called before the FieldList is going to be manipulated.
$this
setForm(Form $form)
Set the Form instance for this FieldList.
$this
setValues(array $data)
Load the given data into this form.
FieldList
HiddenFields()
Return all fields in a form - including fields nested in CompositeFields.
Useful when doing custom field layouts.
VisibleFields()
Return all fields except for the hidden fields.
Useful when making your own simplified form layouts.
FieldList
transform(FormTransformation $trans)
Transform this FieldList with a given transform method, e.g. $this->transform(new ReadonlyTransformation())
CompositeField|null
getContainerField()
No description
$this
setContainerField(CompositeField|null $field)
No description
FieldList
makeReadonly()
Transforms this FieldList instance to readonly.
makeFieldReadonly(string|array|FormField $field)
Transform the named field into a readonly field.
changeFieldOrder(array $fieldNames)
Change the order of fields in this FieldList by specifying an ordered list of field names.
This works well in conjunction with SilverStripe's scaffolding functions: take the scaffold, and shuffle the fields around to the order that you want.
Please note that any tabs or other dataless fields will be clobbered by this operation.
int
fieldPosition(string|FormField $field)
Find the numerical position of a field within the children collection. Doesn't work recursively.
forTemplate()
Default template rendering of a FieldList will concatenate all FieldHolder values.