store related methods

See also the Ariadne General API for newer methods superceding the methods below, mostly in ar\store.

PObject: Store Related Methods

`(mixed)`	`call`	Finds and executes the given template on the current object.
`(mixed)`	`call_super`	Finds and executes the current template (defined before this template) on the current object.
`(int)`	`count_find`	Returns the number of results matching the query.
`(int)`	`count_ls`	Returns the number of children of the current object.
`(mixed)`	`exists`	Searches for the object with the specified path and returns its unique ID, or false if the path doesn't exist.
`(array)`	`find`	Searches for all objects matching the specified criteria and calls the specified template on them. Returns an array of results, if the template returns a result.
`(array)`	`get`	Calls the specified template on the object with the specified path. Returns an array with one result if the template returns a result.
`(array)`	`ls`	Calls each child of the current object with the given template and arguments.
`(array)`	`parents`	Calls each parent of the current object with the specified template and arguments.

Call

(mixed) call($template="view.html", $args="")

`(string)`	`$template`	The name of the template to call on each matching object.
`(array)`	`$args`	The list of arguments to pass on to the template.

call() will run the given template on the current object. The template must be defined somewhere in the parents (including the current object itself) or loaded as a library. Call will return whatever value the template returns.

example 1: calling a menu template, passing the current objects path

<pinp>
  call('view.menu.html', array('current' => $path));
</pinp>

example 2: retrieving the icon url for the current objects' type.

<pinp>
  $icon = call('system.get.icon.phtml');
</pinp>

Call_super

(mixed) call_super()

`(string)`	`$template`	The name of the template to call on each matching object.
`(array)`	`$args`	The list of arguments to pass on to the template.

call_super() will call the template with the same name that was defined on a different level. This can be used to chain unnamed libraries together if they all use call super in a given template name.

example 1: adding typetree names and icons for the current library (typetree.ini in the library)

<pinp>
  call_super();
  $arTypeNames = getvar('arTypeNames');
  $arTypeIcons = getvar('arTypeIcons');


  
  $arTypeNames['pdir.subtype'] = 'Directory subtype';
  $arTypeIcons['pdir.subtype'] = $arTypeIcons['pdir'];

  
  putvar('arTypeIcons', $arTypeIcons);
  putvar('arTypeNames', $arTypeNames);
</pinp>

Count_find

(int) count_find($query="")

(string) $query The search query. See find() for the format.

count_find() works the same as the find() method, but it doesn't call a template on each object that matches the search query. Instead it only returns the number of results found.

example 3: counting all objects with a name starting with 'A'

<pinp>
  $total_names_a = count_find("name.value ~= 'A%'");
</pinp>

Count_ls

(int) count_ls()

count_ls() works the same as the count_find() method, but without the query. It simply returns the total number of direct children of the current object.

Exists

(mixed) exists($path)

(string) $path The path of an object to check.

exists() returns false if the given path does not exists in Ariadne's store. If an object with that path does exists, it returns the objects' id instead. This id is guaranteed to be greater than 0, so you can use it as if it just returns a boolean true or false. The id is further guaranteed to be unique in Ariadne. It is not globally unique.

Find

(array) find($query="", $template="list.html", $args="", $limit=100, $offset=0)

`(string)`	`$query`	The search query. See below for the format.
`(string)`	`$template`	The name of the template to call on each matching object.
`(array)`	`$args`	The list of arguments to pass on to the template.
`(int)`	`$limit`	The maximum number of objects to find.
`(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.

Query Format

$query = "propertyName.valueName compare $value";

The query string format is a bit like SQL, but geared only to data retrieval. You can search on any Ariadne property, a short list is presented below. The valid compare methods are:

<	smaller	`"time.ctime < ".(time()-72460*60))`
<=	smaller or equal	`"article.start <= ".time()`
!=	not equal	`"object.path != '".$path."'"`
>	larger	`"article.end > ".time()`
>=	larger or equal	`"object.priority >= 0"`
=	equal	`"object.parent = '".$path."'"`
~=	like	`"name.value ~= 'A%'"`
!~	not like	`"object.path !~ '".$path."%'"`

For like (~=) and not like (!~) the '%' character is used as a wildcard, it will match any string.

List of most used properties in Ariadne.

object	implements	Matches if the type matches any of the parent classes of the object
	parent	Path of the parent object
	path	Path of the object itself
	priority	The priority of the object
	type	The type (class) of the object, e.g. pobject or ppage
name	value	The name of the object, $nlsdata->name
	nls	The language code of this name
text	value	Any text in the object, the name, summary or page.
	nls	The language code of this text
time	ctime	The unix timestamp of the creation of the object
	mtime	The last time the object was changed
	muser	The login of the user that last changed the object
custom	name	The name of a custom property
	value	The value of that custom property
	nls	The language code of that custom property, or 'none'.

You can combine multiple properties, or multiple values of a property, in a single query, e.g.:

  $query = "name.value ~='A%' and name.nls = 'en'";

This query matches any object whose name starts with 'A' in english.

  $query = "object.implements = 'ppage' and time.ctime > ".$lastweek;

Will match any object whose class is a subclass of ppage and which is created within the last week.

You can use both AND and OR to combine properties. Use ( and ) to make clear how these properties should be combined. e.g.:

  $query = "object.implements = 'ppage' or ".
           "( object.type = 'pphoto' and time.ctime > $lastweek )";

This will match all page objects, or subclasses thereof, and all pphoto objects created in the last week.

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 ).

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."'";

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.

Get

(array) get($path, $template='view.html', $args='')

`(string)`	`$path`	The path of the object to call.
`(string)`	`$template`	The template to call on the object.
`(array)`	`$args`	The arguments for the template.

get() calls a template on an object in the Ariadne store. If the template returns a value, it will be returned as the first value in the return array. Get will always return an array, but it will be empty if the template called doesn't return a value.

example 4: retrieving the name of a specific object

<pinp>
  $aName = current(get('/an/object/', 'system.get.name.phtml'));
</pinp>

Ls

(array) ls($template='list.html', $args='')

`(string)`	`$template`	The template to call on the child objects.
`(array)`	`$args`	The arguments for the template.

ls() calls the given template on all direct children of the current object. It returns the results of each object called in an array. If the template doesn't return anything, the array will be empty. ls() will call each object in the order defined by priority, highest first, and then path, alphabetically, 'a' first.

Parents

(int) parents($template='', $args='', $top='/')

`(string)`	`$template`	The template to call on the parent objects.
`(array)`	`$args`	The arguments for the template.
`(string)`	`$top`	The top-most parent to call.

parents() calls all the parents of the current object, upto and including the parent indicated by $top. It will return an array with the results of the template, with the top-most parent first. If the template returns no values, the array will be empty.

example 5: breadcrumb trail

<ul class="breadcrumbs"><pinp>
  parents('show.breadcrumb.html', '', currentsite());
</pinp></ul>

More than a CMS