Developers > Kernel Documentation > Data Handling >


This class represents a list of ExSite::Object objects (in most cases, this is a list of datahashes). It is typically used to represent a set of records from the database. Common list-handling methods are supported, such as count, push, pop, shift, and unshift.

Standalone Objects can be extracted from the ObjectList using a variety of methods.

The ObjectList has an index attribute, which points to a particular item in the list. When this is defined, the ObjectList also has the characteristics of an individual Object, and inherits all the methods of the Object class for that purpose. The index can be used to address particular list items, or to iterate through the list. That means the following operations are equivalent:

    # edit the 6th element of the list (index 5)
    my $obj = $list->newobj();
    print $obj->edit();

    # ditto
    print $list->edit();

The index is reset when certain list-altering operations are performed.

Define an ObjectList


Instantiates a new ObjectList. Attributes that can be defined in the %opt hash include type (usually a table whose data is represented in the list), list (an array of datahashes to initialize the object with), and match (a match hash to look up data to initialize the object with).


Fetch a list of datahashes from the database to fill the ObjectList. They are fetched from the table defined by the type attribute, according to the selection criteria in the $match hash.

List Contents and Data


Returns the number of items in the list.


Gets the current index pointer into the list, as an integer. (First item is at index 0.)


Sets the current index pointer into the list.


Clears the index pointer.


Sets the whole list to the values in @list. Resets the index.


Returns the list as an array of datahashes.

List Operations


Pushes @list onto the end of the ObjectList.


Pops the last item in the list, and returns it as an Object.


Shifts the first item off the list, and returns it as an Object.


Pushes @list onto the front of the ObjectList.


Cuts the current element (the one that is pointed to by index) out of the list, and splices the rest of the list together.


Advances the index pointer to the next item in the list, and returns that item as an Object. If at the end of the list, returns undef

and resets the index pointer. Subsequent calls to next() will then begin iterating from the start of the list again.

List Order


Re-orders the list in order of the given keys. The keys are hash keys of the individual list elements, and the sort order is determined by the values under those keys. If more than one key is given, then the list elements are sorted in that key order (ie. by key1 first, then by key2 if key1 is identical, etc.)


Reverses the order of the list.


Returns a hash of the list elements, indexed by $key. This is analogous to ExSite::Misc::keywise(), except that the hash values are ExSite::Objects.

Displaying Lists


Returns a formatted HTML report of the items in the list. By default this is built using ExSite::Report::report.