find

`(array) find($criteria, $function="list.html", $args="", $limit=100, $offset=0)`

Searches for all objects matching the criteria, and calls the template on them.

Argument Description

(mixed) $criteria The search criteria, either as an array or a query string.

(string) $function The name of the template to call on each result.

(mixed) $args Arguments to that template, as urlencoded string, or an array

(int) $limit The maximum number of objects to call.

(int) $offset The number of objects to skip.

find() will search the ariadne tree, using the current object as the starting point, or root of the search, for all objects which fulfill the search criteria.

On each object found it calls the given template with the given arguments. It will limit the number of retrieved objects to the given limit, while skipping over the first n objects, as declared with the offset parameter.

$criteria must be either an array with a fixed format, or a valid query string:

$criteria["prop_name"]["value_name"]["compare"]=$value

$criteria="prop_name.value_name compare $value";

The query string format also understands AND and OR , as well as grouping criteria using braces '( ' and ') '.

The valid values for prop_name and value_name are described in the property tabs on each class, the most common are:

Property	Length	Description
(string) custom.name	32	The name of the custom property.
(string) custom.value	128	The value of the custom property.
(string) custom.nls	4	The language code the value.
(string) name.value	128	The name of the object.
(string) name.nls	4	The language code of the name.
(string) object.implements	16	Class or interface the object must implement.
(int) object.lastchanged	n/a	Timestamp of the last save of the object.
(string) object.parent	128	Path of the parent of the object.
(string) object.path	128	Path of the object itself.
(int) object.priority	n/a	Priority of the objects node.
(string) object.type	16	Classname of the object.
(string) text.value	128	A text in the object, names, summaries, etc.
(string) text.nls	4	language code of the text.
(int) time.ctime	n/a	Timestamp of the creation of the object.
(int) time.mtime	n/a	Timestamp of the last modification of the object.
(string) time.muser	32	Login of the user that last modified the object.
(string) value.value	128	Value of the 'value' field of a pobject.

The valid compare function are:

Compare functions	Description
<	Smaller
<=	Smaller or equal
<>, !=	Not equal
>	Larger
>=	Larger or equal
=	Equal
~=	Like
!~	Not like

Custom properties

You can query a custom property (a property defined via the custom fields wizard) by prefixing the name of the property with 'my.' e.g.:

  $query="my.price >= 90";

If the property is language dependant, you can define the language like this:

  $query="my.description ~= '%".AddSlashes($keyword)."%'".
         " and my.nls='".$nls."'";

Ordering and limiting

Find by default returns a maximum of 100 results, ordered by priority and pathname. If you want more results you must specify the new limit. This can be done via the $limit argument, or via the query syntax, like this:

  $query="object.parent='".AddSlashes($path)."'".
         " limit ".$newlimit;

In addition you can specify an offset, allowing you to 'page' through results:

  $query="object.parent='".AddSlashes($path)."'".
         " limit ".$newoffset.",".$newlimit;

Finally you can order the results on any property, via the 'order by' statement:

  $query="object.parent='".AddSlashes($path)."'".
         " and name.nls='".$nls."'".
         " order by name.value ASC ".
         " limit ".$newoffset.",".$newlimit;

In the last query we've made find() act like the ls() function, with the results ordered by the name property instead. Since names can be stored in multiple languages we've also added the criteria that the name to be used is the name for the current language. Finally the 'ASC ' tells find to order the names in ascending order, instead of descending order (DESC ).

Multiple checks on a single property

For some properties multiple values are stored for a single object. In some cases you may need to check more than one of these values based on different criteria. You can do this via the following query syntax:

  $query=
    "( my.keyword:a.value='".AddSlashes($keyword1)."'".
    " and my.keyword:a.nls='".$nls."' )".
    " and ( my.keyword:b.value='".AddSlashes($keyword2)."'".
    " and my.keyword:b.nls='".$nls."')";

The ':a ' and ':b ' define 'tags' for that specific match, so that firstly the query engine knows that keyword1 and keyword2 do not need to match both with the same property record, just as long as there is a matching record for both of them, and secondly it also knows which nls field must match with which record, although in this case they're both the same.

Examples

Searching for current news items using a criteria array.

<pinp>
  $searchtext=getvar('searchtext');
  $criteria["timeframe"]["start"]["<="] = time();
  $criteria["timeframe"]["end"][">="] = time();
  $criteria["text"]["value"]["~="] =
     "'%".AddSlashes($searchtext)."%'";
  find($criteria, "show.html");
</pinp>

Searching for directories in the direct children of the current object.

<pinp>
  $query="object.implements = 'pdir' ".
         " and object.parent = '".AddSlashes($path)."'";
  find($query, "show.html");
</pinp>