In the HomePage.php file (or whatever page type you're wanting to iterate over data on):

In the HomePage.ss template (or respective template for your page type inside templates for your current theme):

You use <% control MyFunctionReturningADataObjectSet %> to iterate over data. DataObject::get() returns a DataObjectSet, so we can iterate over the DataObject's in the set by using <% control UpcomingEvents(5) %> in this case. You'll also note that we used (5), this means you can effectively apply a limit on the records returned from the template, which defaults to 5 if you just use <% control UpcomingEvents %> without the argument.

The second and third arguments to DataObject::get() are for filter, and sort respectively. And, the 5th argument is how many items you want to return, so you can effectively establish a limit of how many records to return. This means you can sort by a date, for example:

Pagination can also be applied, if you limit a set.

Here's some useful references in the SS documentation wiki:

http://doc.silverstripe.com/doku.php?id=private:recipes:pagination
http://doc.silverstripe.com/doku.php?id=dataobjectset
http://doc.silverstripe.com/doku.php?id=templates

Hope this explains what you're after!

Sean

Sorted! Thanks to Sean for his help, I came up with something that works.

function NextEvent() {
   $eventHolder = DataObject::get_one("EventHolder");
   $events = DataObject::get("EventPage", "ParentID = $eventHolder->ID", "Date ASC", "", "");

   foreach( $events as $event ) {
      if( $event->Date >= date('Y-m-d') ) {
         break;
         }
      }
   return( $event);
   }
}

Any comments on a better way to do this, ie more efficent would be appreciated.

you can use MySQLs NOW() command aswell I would assume