So far you've been introduced to the basics of the Limb. The idea of the active site objects placed in the object tree is central in Limb. Pretty straightforward question is 'how do i query all those objects?'. This mini howto should provide you with some answers

All Limb site object queries are executed via special 'fetcher' mechanism.

In general there 2 kinds of fetching operations:

• single object query
• multiple objects query

It allows to query the object tree in several ways:

• via object tree path
• via node_id
• via set of nodes
• via current request URI

The fetcher not just simply fetches site objects it also apply <a href='/root/documentation/AccessPolicy'>access policy]] and returns ONLY site objects accessible for the current user.

For your convinience all fetcher methods can be invoked with global functions named identically.

Before describing the available fetching methods a quick intro into Limb fetching mechanism should be done.

What the fetcher actually does can be described as following steps:

• Find a site object in the object tree by some search criteria
• Apply access policy rules in order to determine whether the requested object is accessible at all
• Call site object's specified fetch() method in order to let the site object load its very specific data. It's a rare situation that you need to override the basic site object behaviour. It concerns complex site(content) objects only. We've faced several cases so far, one of them is the image object where you're required to fetch additional information on image variations.
• Call site object's specified count() method in order to let the site object count total fetched elements. Limb never gets the whole resulting set: it would be a kill for PHP. All fetching opearations are limited on the database level. This is very important, since it allows to use very effective SQL 'count-only' queries. However it's quite uncommon that you need to override the base class behaviour.

PHP object slowliness is well known, objects add a good overhead. Especially for this reason all fetching operations return arrays instead of objects.

This behaviour turned out to be very useful with WACT templates. Object arrays flow into template components and you can access objects' attributes in a natural way.

However you can easily turn these arrays into fully qualified site objects with call to the special function:

 wrap_with_site_object($fetched_data) 

In the documentation we refer to fetched objects rather than fetched arrays - we hope this won't confuse you much

There are 3 methods in the fetcher class allowing you to fetch single site objects:

  fetch_one_by_node_id($node_id)

returns the fetched object attached to the tree node which has $node_id id

 fetch_one_by_path($path)

returns the fetched object attached to the tree node which specified tree path(e.g. site object at '/root/artticle/1' path can be fetched with fetch_one_by_path('/root/article/1') call)

 fetch_mapped_by_url()

returns the object mapped by the request URL. Also is capable of fetching the object via generic URL path to the object http://domain.com/root?node_id=$id.

Fetching multiple objects differs from fetching single ones. For speed's sake used only one loader - site object which fetching and counting methods are called, since heterogeneous objects are returned and calling these methods for every one is too slow.

What does it mean? In practice you rarely need all specific attributes of all objects in the fetched dataset(e.g. different image variations of the image object). Technically it's possible…yet try to imagine what happens when the whole tree of objects is fetched!

There are 4 methods to fectch a group of site objects at once:

fetch($loader_class_name, &$counter, $params = array(), $fetch_method = 'fetch')

returns the set of fetched objects, loaded by $loader_class_name(mostly 'site_object') by invoking its $fetch_method. $counter is set to total number of fetched elements. $params allows you to apply limit, offset, etc.

Example:

$params = array('limit' => 10, 'offset' => 1);
$counter = 0;
$users =& fetch('user_object', $counter, $params);

fetch_sub_branch($path, $loader_class_name, &$counter, $params = array(), $fetch_method = 'fetch_by_ids')

returns the set of fetched objects, loaded by $loader_class_name(mostly 'site_object') from the object tree starting from $path location by invoking its $fetch_method. $counter is set to total number of fetched elements. $params allows you to apply limit, offset, depth, etc.

Example:

$params = array('limit' => 10, 'offset' => 1, 'depth' => 1);
$counter = 0;
$user_groups =& fetch_sub_branch('/root/user_groups', 'user_group', $counter, $params);

fetch_by_node_ids($node_ids, $loader_class_name, &$counter, $params = array(), $fetch_method = 'fetch_by_ids')

returns the set of fetched objects, loaded by $loader_class_name(mostly 'site_object') specified by array of nodes in $node_ids by invoking its $fetch_method. $counter is set to total number of fetched elements. $params allows you to specify some additional params.

Example:

$counter = 0;
$user_groups =& fetch_by_node_ids(array(10,11), 'user_group', $counter);

fetch_by_ids($object_ids, $loader_class_name, &$counter, $params = array(), $fetch_method = 'fetch_by_ids')

returns the set of fetched objects, loaded by $loader_class_name(mostly 'site_object') specified by array of object ids in $object_ids by invoking its $fetch_method. $counter is set to total number of fetched elements. $params allows you to specify some additional params.

Example:

 $counter = 0;
 $user_groups =& fetch_by_ids(array(100,81), 'user_group', $counter);