Version: current

# Class DataObjectSet

This class represents a set of `ViewableData` subclasses (mostly `DataObject` or `ArrayData`). It is used by the ORM-layer of Silverstripe to return query-results from `SQLQuery`.

  Object
  ViewableData implements IteratorAggregate
  DataObjectSet implements IteratorAggregate, Countable

### Direct known subclasses

`ComponentSet`, `FieldSet`

### Indirect known subclasses

`HiddenFieldSet`, `Member_GroupSet`

Package: sapphire\model
Located at sapphire/core/model/DataObjectSet.php

## Methods summary

`public` | # `__construct( `ViewableData`|array|mixed $items = null )` Create a new DataObjectSet. If you pass one or more arguments, it will try to convert them into `ArrayData` objects. Create a new DataObjectSet. If you pass one or more arguments, it will try to convert them into `ArrayData` objects. #### Parameters $items ViewableData|array|mixed $items Parameters to use in this set, either as an associative array, object with simple properties, or as multiple parameters. #### Overrides `Object::__construct`
`public` | # `destroy( )` Destory all of the DataObjects in this set. Destory all of the DataObjects in this set.
`public` | # `emptyItems( )` Removes all the items in this set. Removes all the items in this set.
`public array` | # `toArray( string $index = null )` Convert this DataObjectSet to an array of DataObjects. Convert this DataObjectSet to an array of DataObjects. #### Parameters $index string $index Index the array by this field. #### Returns `array` array
`public array` | # `toNestedArray( string $index = null )` Convert this DataObjectSet to an array of maps. Convert this DataObjectSet to an array of maps. #### Parameters $index string $index Index the array by this field. #### Returns `array` array
`public array` | # `toDropDownMap( string $index = 'ID', string $titleField = 'Title', string $emptyString = null, boolean $sort = false )` Returns an array of ID => Title for the items in this set. Returns an array of ID => Title for the items in this set. This is an alias of DataObjectSet->map() #### Deprecated 2.5 Please use map() instead #### Parameters $index string $index The field to use as a key for the array $titleField string $titleField The field (or method) to get values for the map $emptyString string $emptyString Empty option text e.g "(Select one)" $sort bool $sort Sort the map alphabetically based on the $titleField value #### Returns `array` array
`public` | # `setPageLength( integer $length )` Set number of objects on each page. Set number of objects on each page. #### Parameters $length int $length Number of objects per page
`public` | # `setPageLimits( integer $pageStart, integer $pageLength, integer $totalSize )` Set the page limits. Set the page limits. #### Parameters $pageStart int $pageStart The start of this page. $pageLength int $pageLength Number of objects per page $totalSize int $totalSize Total number of objects.
`public array` | # `getPageLimits( )` Get the page limits Get the page limits #### Returns `array` array
`public` | # `parseQueryLimit( `SQLQuery` $query )` Use the limit from the given query to add prev/next buttons to this DataObjectSet. Use the limit from the given query to add prev/next buttons to this DataObjectSet. #### Parameters $query SQLQuery $query The query used to generate this DataObjectSet
`public integer` | # `CurrentPage( )` Returns the number of the current page. Returns the number of the current page. #### Returns `integer` int #### Overrides `ViewableData::CurrentPage`
`public integer` | # `TotalPages( )` Returns the total number of pages. Returns the total number of pages. #### Returns `integer` int
`public `DataObjectSet`` | # `Pages( integer $maxPages = 0 )` Return a datafeed of page-links, good for use in search results, etc. $maxPages will put an upper limit on the number of pages to return. It will show the pages surrounding the current page, so you can still get to the deeper pages. Return a datafeed of page-links, good for use in search results, etc. $maxPages will put an upper limit on the number of pages to return. It will show the pages surrounding the current page, so you can still get to the deeper pages. #### Parameters $maxPages int $maxPages The maximum number of pages to return #### Returns ``DataObjectSet`` DataObjectSet
`public` | # `PaginationSummary( mixed $context = 4 )`
`public boolean` | # `NotFirstPage( )` Returns true if the current page is not the first page. Returns true if the current page is not the first page. #### Returns `boolean` boolean
`public boolean` | # `NotLastPage( )` Returns true if the current page is not the last page. Returns true if the current page is not the last page. #### Returns `boolean` boolean
`public boolean` | # `MoreThanOnePage( )` Returns true if there is more than one page. Returns true if there is more than one page. #### Returns `boolean` boolean
`public` | # `FirstItem( )`
`public` | # `LastItem( )`
`public string` | # `PrevLink( )` Returns the URL of the previous page. Returns the URL of the previous page. #### Returns `string` string
`public string` | # `NextLink( )` Returns the URL of the next page. Returns the URL of the next page. #### Returns `string` string
`public` | # `setPaginationGetVar( string $var )` Allows us to use multiple pagination GET variables on the same page (eg. if you have search results and page comments on a single page) Allows us to use multiple pagination GET variables on the same page (eg. if you have search results and page comments on a single page) Example: @see PageCommentInterface::Comments() #### Parameters $var string $var The variable to go in the GET string (Defaults to 'start')
`public` | # `push( `DataObject` $item, string $key = null )` Add an item to the DataObject Set. Add an item to the DataObject Set. #### Parameters $item DataObject $item Item to add. $key string $key Key to index this DataObject by.
`public` | # `insertFirst( `DataObject` $item, string $key = null )` Add an item to the beginning of the DataObjectSet Add an item to the beginning of the DataObjectSet #### Parameters $item DataObject $item Item to add $key string $key Key to index this DataObject by.
`public` | # `unshift( `DataObject` $item )` Insert a DataObject at the beginning of this set. Insert a DataObject at the beginning of this set. #### Parameters $item DataObject $item Item to insert.
`public `DataObject`` | # `shift( )` Remove a DataObject from the beginning of this set and return it. This is the equivalent of pop() but acts on the head of the set. Opposite of unshift(). Remove a DataObject from the beginning of this set and return it. This is the equivalent of pop() but acts on the head of the set. Opposite of unshift(). #### Returns ``DataObject`` (or null if there are no items in the set)
`public `DataObject`` | # `pop( )` Remove a DataObject from the end of this set and return it. This is the equivalent of shift() but acts on the tail of the set. Opposite of push(). Remove a DataObject from the end of this set and return it. This is the equivalent of shift() but acts on the tail of the set. Opposite of push(). #### Returns ``DataObject`` (or null if there are no items in the set)
`public` | # `remove( `DataObject` $itemObject )` Remove a DataObject from this set. Remove a DataObject from this set. #### Parameters $itemObject DataObject $itemObject Item to remove.
`public` | # `replace( `DataObject` $itemOld, `DataObject` $itemNew )` Replaces $itemOld with $itemNew Replaces $itemOld with $itemNew #### Parameters $itemOld DataObject $itemOld $itemNew DataObject $itemNew
`public` | # `merge( `DataObjectSet` $anotherSet )` Merge another set onto the end of this set. Merge another set onto the end of this set. #### Parameters $anotherSet DataObjectSet $anotherSet Set to mege onto this set.
`public `DataObjectSet`` | # `getRange( integer $offset, integer $length )` Gets a specific slice of an existing set. Gets a specific slice of an existing set. #### Parameters $offset int $offset $length int $length #### Returns ``DataObjectSet`` DataObjectSet
`public `DataObjectSet_Iterator`` | # `getIterator( )` Returns an Iterator for this DataObjectSet. This function allows you to use DataObjectSets in foreach loops Returns an Iterator for this DataObjectSet. This function allows you to use DataObjectSets in foreach loops #### Returns ``DataObjectSet_Iterator`` DataObjectSet_Iterator #### Overrides `ViewableData::getIterator` #### Implementation of `IteratorAggregate::getIterator()`
`public boolean` | # `exists( )` Returns false if the set is empty. Returns false if the set is empty. #### Returns `boolean` boolean #### Overrides `Object::exists`
`public `DataObject`` | # `First( )` Return the first item in the set. Return the first item in the set. #### Returns ``DataObject`` DataObject #### Overrides `ViewableData::First`
`public `DataObject`` | # `Last( )` Return the last item in the set. Return the last item in the set. #### Returns ``DataObject`` DataObject #### Overrides `ViewableData::Last`
`public integer` | # `TotalItems( )` Return the total number of items in this dataset. Return the total number of items in this dataset. #### Returns `integer` int #### Overrides `ViewableData::TotalItems`
`public integer` | # `Count( )` Returns the actual number of items in this dataset. Returns the actual number of items in this dataset. #### Returns `integer` int
`public string` | # `UL( )` Returns this set as a XHTML unordered list. Returns this set as a XHTML unordered list. #### Returns `string` string
`public string` | # `forTemplate( )` Returns this set as a XHTML unordered list. Returns this set as a XHTML unordered list. #### Returns `string` string
`public array` | # `map( string $index = 'ID', string $titleField = 'Title', string $emptyString = null, boolean $sort = false )` Returns an array of ID => Title for the items in this set. Returns an array of ID => Title for the items in this set. #### Parameters $index string $index The field to use as a key for the array $titleField string $titleField The field (or method) to get values for the map $emptyString string $emptyString Empty option text e.g "(Select one)" $sort bool $sort Sort the map alphabetically based on the $titleField value #### Returns `array` array
`public `ViewableData`` | # `find( mixed $key, mixed $value )` Find an item in this list where the field $key is equal to $value Eg: $doSet->find('ID', 4); Find an item in this list where the field $key is equal to $value Eg: $doSet->find('ID', 4); #### Returns ``ViewableData`` The first matching item.
`public array` | # `column( string $value = "ID" )` Return a column of the given field Return a column of the given field #### Parameters $value string $value The field name #### Returns `array` array
`public array` | # `groupBy( string $index )` Returns an array of DataObjectSets. The array is keyed by index. Returns an array of DataObjectSets. The array is keyed by index. #### Parameters $index string $index The field name to index the array by. #### Returns `array` array
`public `DataObjectSet`` | # `GroupedBy( string $index, string $childControl = "Children" )` Groups the items by a given field. Returns a DataObjectSet suitable for use in a nested template. Groups the items by a given field. Returns a DataObjectSet suitable for use in a nested template. #### Parameters $index string $index The field to group by $childControl string $childControl The name of the nested page control #### Returns ``DataObjectSet`` DataObjectSet
`public string` | # `buildNestedUL( array $nestingLevels, string $ulExtraAttributes = "" )` Returns a nested unordered list out of a "chain" of DataObject-relations, using the automagic ComponentSet-relation-methods to find subsequent DataObjectSets. The formatting of the list can be different for each level, and is evaluated as an SS-template with access to the current DataObjects attributes and methods. Returns a nested unordered list out of a "chain" of DataObject-relations, using the automagic ComponentSet-relation-methods to find subsequent DataObjectSets. The formatting of the list can be different for each level, and is evaluated as an SS-template with access to the current DataObjects attributes and methods. Example: Groups (Level 0, the "calling" DataObjectSet, needs to be queried externally) and their Members (Level 1, determined by the Group->Members()-relation). #### Parameters $nestingLevels array $nestingLevels Defines relation-methods on DataObjects as a string, plus custom SS-template-code for the list-output. Use "Root" for the current DataObjectSet (is will not evaluate into a function). Caution: Don't close the list-elements (determined programatically). You need to escape dollar-signs that need to be evaluated as SS-template-code. Use $EvenOdd to get appropriate classes for CSS-styling. Format: array( array( "dataclass" => "Root", "template" => "\$AccountName" ), array( "dataclass" => "GrantObjects", "template" => "#\$GrantNumber: \$TotalAmount.Nice, \$ApplicationDate.ShortMonth \$ApplicationDate.Year" ) ); $ulExtraAttributes string $ulExtraAttributes Extra attributes #### Returns `string` Unordered List (HTML)
`public string` | # `getChildrenAsUL( array $nestingLevels, integer $level = 0, string $template = "<li id=\"record-\$ID\" class=\"\$EvenOdd\">\$Title", string $ulExtraAttributes = null, mixed & $itemCount = 0 )` Gets called recursively on the child-objects of the chain. Gets called recursively on the child-objects of the chain. #### Parameters $nestingLevels array $nestingLevels see {@buildNestedUL} $level int $level Current nesting level $template string $template Template for list item $ulExtraAttributes string $ulExtraAttributes Extra attributes $itemCount #### Returns `string` string
`public` | # `sort( string $fieldname, string $direction = "ASC" )` Sorts the current DataObjectSet instance. Sorts the current DataObjectSet instance. #### Parameters $fieldname string $fieldname The name of the field on the DataObject that you wish to sort the set by. $direction string $direction Direction to sort by, either "ASC" or "DESC".
`public` | # `removeDuplicates( string $field = 'ID' )` Remove duplicates from this set based on the dataobjects field. Assumes all items contained in the set all have that field. Remove duplicates from this set based on the dataobjects field. Assumes all items contained in the set all have that field. #### Parameters $field string $field the field to check for duplicates
`public string` | # `debug( )` Returns information about this set in HTML format for debugging. Returns information about this set in HTML format for debugging. #### Returns `string` string
`public `DataObjectSet`` | # `groupWithParents( string $groupField, string $groupClassName, string $sortParents = null, string $parentField = 'ID', boolean $collapse = false, string $requiredParents = null )` Groups the set by $groupField and returns the parent of each group whose class is $groupClassName. If $collapse is true, the group will be collapsed up until an ancestor with the given class is found. Groups the set by $groupField and returns the parent of each group whose class is $groupClassName. If $collapse is true, the group will be collapsed up until an ancestor with the given class is found. #### Parameters $groupField string $groupField The field to group by. $groupClassName string $groupClassName Classname. $sortParents string $sortParents SORT clause to insert into the parents SQL. $parentField string $parentField Parent field. $collapse boolean $collapse Collapse up until an ancestor with the given class is found. $requiredParents string $requiredParents Required parents #### Returns ``DataObjectSet`` DataObjectSet
`public` | # `addWithoutWrite( `DataObject` $field )` Add a field to this set without writing it to the database Add a field to this set without writing it to the database #### Parameters $field DataObject $field Field to add
`public` | # `containsIDs( mixed $idList )` Returns true if the DataObjectSet contains all of the IDs givem Returns true if the DataObjectSet contains all of the IDs givem #### Parameters $idList $idList An array of object IDs
`public` | # `onlyContainsIDs( mixed $idList )` Returns true if the DataObjectSet contains all of and only the IDs given. Note that it won't like duplicates very much. Returns true if the DataObjectSet contains all of and only the IDs given. Note that it won't like duplicates very much. #### Parameters $idList $idList An array of object IDs
`public boolean` | # `hasValue( string $field = false, array $arguments = null, boolean $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. 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. #### Parameters $field string $field $arguments array $arguments $cache bool $cache #### Returns `boolean` bool #### Overrides `ViewableData::hasValue`

### Methods inherited from ViewableData

`ATT_val()`, `BaseHref()`, `CSSClasses()`, `ColumnBreak()`, `ColumnCalc()`, `ColumnNumber()`, `ColumnPad()`, `ColumnPos()`, `CurrentMember()`, `Debug()`, `Even()`, `EvenOdd()`, `FirstLast()`, `HasPerm()`, `IsAjax()`, `JS_val()`, `Me()`, `Middle()`, `MiddleString()`, `Modulus()`, `MultipleOf()`, `Odd()`, `Pos()`, `RAW_val()`, `SQL_val()`, `ThemeDir()`, `ThemeName()`, `Top()`, `XML_val()`, `__get()`, `__isset()`, `__set()`, `buildCastingCache()`, `cachedCall()`, `castingClass()`, `castingHelper()`, `castingHelperPair()`, `castingObjectCreator()`, `castingObjectCreatorPair()`, `customise()`, `defineMethods()`, `escapeTypeForField()`, `getField()`, `getSecurityID()`, `getXMLValues()`, `hasField()`, `i18nLocale()`, `iteratorProperties()`, `obj()`, `renderWith()`, `setCustomisedObj()`, `setField()`

### Methods inherited from Object

`__call()`, `__toString()`, `__wakeup()`, `addMethodsFrom()`, `addStaticVars()`, `addWrapperMethod()`, `add_extension()`, `add_static_var()`, `allMethodNames()`, `cacheToFile()`, `cacheToFileWithArgs()`, `clearCache()`, `combined_static()`, `create()`, `createMethod()`, `create_from_string()`, `extInstance()`, `extend()`, `getCustomClass()`, `getExtensionInstance()`, `getExtensionInstances()`, `get_extensions()`, `get_static()`, `hasExtension()`, `hasMethod()`, `has_extension()`, `invokeWithExtensions()`, `is_a()`, `loadCache()`, `parentClass()`, `parse_class_spec()`, `remove_extension()`, `sanitiseCachename()`, `saveCache()`, `set_stat()`, `set_static()`, `set_uninherited()`, `stat()`, `strong_create()`, `uninherited()`, `uninherited_static()`, `useCustomClass()`

### Methods inherited from Countable

`count()`

### Magic methods summary

## Properties summary

`protected array` | $items | # The DataObjects in this set. The DataObjects in this set.
`protected integer` | $odd | #
`protected boolean` | $first | # True if the current DataObject is the first in this set. True if the current DataObject is the first in this set.
`protected boolean` | $last | # True if the current DataObject is the last in this set. True if the current DataObject is the last in this set.
`protected `DataObject`` | $current | # The current DataObject in this set. The current DataObject in this set.
`protected integer` | $pageStart | # The number object the current page starts at. The number object the current page starts at.
`protected integer` | $pageLength | # The number of objects per page. The number of objects per page.
`protected integer` | $totalSize | # Total number of DataObjects in this set. Total number of DataObjects in this set.
`protected string` | $paginationGetVar | # The pagination GET variable that controls the start of this set. The pagination GET variable that controls the start of this set.

### Properties inherited from ViewableData

`$casting`, `$customisedObject`, `$default_cast`, `$failover`, `$iteratorPos`, `$iteratorTotalItems`

### Properties inherited from Object

`$class`, `$extension_instances`, `$extensions`

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -