fetch( 'content', 'keyword', hash( 'alphabet', alphabet, [ 'strict_matching', strict_matching, ] [ 'classid', classid, ] [ 'offset', offset, ] [ 'limit', limit, ] [ 'owner', owner, ] [ 'parent_node_id', parent_node_id, ] [ 'include_duplicates', include_duplicates, ] [ 'sort_by', sort_by ] ) )
| Name | Type | Description | Required |
|---|---|---|---|
| alphabet | string | The sequence that should be matched. | Yes. |
| strict_matching | boolean | Enables or disables exact matching. If FALSE (or omitted), the function will look for keywords that start with the specified sequence. | No. |
| classid | array | Filtering: the ID number of the class or an array of the ID numbers. | No. |
| offset | integer | The offset to start at. | No. |
| limit | integer | The number of elements that should be returned. | No. |
| owner | integer | Filtering by owner: the ID number of the object representing the user. | No. |
| parent_node_id | integer | The ID number of the parent node. | No. |
| include_duplicates | boolean | Makes it possible to avoid duplicates (different keywords but same nodes) in the result. If TRUE (or omitted), duplicates are allowed. | No. |
| sort_by | array | The sorting mechanism that should be used. | No. |
An array of hashes (see below) or FALSE.
This function fetches nodes that encapsulate objects which make use of certain keywords. It returns an array of hashes where each hash represents a "keyword-node" pair.
The keyword must be provided using the "alphabet" parameter. This parameter can be a letter, a part of a word or an entire word - the function will look for keywords that start with the specified sequence. This means that if you specify "car" in the "alphabet" parameter, the system will look for keywords like "car", "card", "carnival", "car painting" and so on (but not "scarf" for example). Every time such a keyword is found, the main node of the object that uses this keyword will be included in the result along with the matching keyword. Note that if an object contains multiple keywords that start from the specified sequence, the main node of this object will be fetched several times. The following table shows an example of the structure that may be returned if there are three articles that contain matching keywords:
| Keyword | Node |
|---|---|
| car enamel |
The main node of the "Auto" article (as a ezcontentobjecttreenode object). |
| car painting |
The main node of the "Auto" article (as a ezcontentobjecttreenode object). |
| car sickness |
The main node of the "Driving" article (as a ezcontentobjecttreenode object). |
| cars |
The main node of the "Traffic" article (as a ezcontentobjecttreenode object). |
As you can see from the table, the article called "Auto" uses two keywords that start from "car": "car enamel" and "car painting". The remaining two articles ("Driving" and "Traffic") make use of one keyword each: "car sickness" and "cars".
The "strict_matching" parameter is optional and can be set to either true() or false(). When set to true(), the fetch function will look for the exactly same keyword as the specified sequence. For example, if the "alphabet" parameter is set to "car", only items that use "car" as a keyword will be fetched; keywords like "card", "carnival", "car painting" and so on will be ignored.
By default, the function will fetch nodes that encapsulate objects of all types created by any user. However, it is possible to fetch objects of a certain type or that were created by a specific user, by using the optional "classid" and "owner" parameters. The "offset" and "limit" parameters can be used to limit the result.
The optional "parent_node_id" parameter makes it possible to fetch nodes that are directly under the specified parent node. If an object makes use of a keyword that starts with the specified sequence, the function will check if the main node of this object is a child on the specified parent node. If yes, it will be included in the result.
The "include_duplicates" parameter makes it possible to avoid duplicates (different keywords but same nodes) in the result. This parameter is optional and can be set to either true() or false(). When set to false(), the result will only contain unique nodes. For example, if an article contains both "car enamel" and "car painting" keywords, and you specify "car" in the "alphabet" parameter, the main node of this article will be included in the result once. The corresponding keyword-node pair will contain the original sequence ("car") instead of the actual keyword that was matched ("car enamel" or "car painting"). The following table shows the structure that would be returned if the "include_duplicates" parameter is set to false() in the three-articles example above:
| Keyword | Node |
|---|---|
| car |
The main node of the "Auto" article (as a ezcontentobjecttreenode object). |
| car sickness |
The main node of the "Driving" article (as a ezcontentobjecttreenode object). |
| cars |
The main node of the "Traffic" article (as a ezcontentobjecttreenode object). |
The "sort_by" parameter makes it possible to sort the result in different ways. This parameter must be provided as an array. The first element of the array must be the desired sorting method. The second element of the array must be the sorting direction, it can be either true() or false() - ascending or descending. Note that this parameter works in the very same way as the "sort_by" parameter of the list fetch function. However, it currently only supports the following sorting methods:
Note that using other sort methods will lead to an error.
The function returns an array of hashes. Each hash consists of the following elements:
| Key | Type | Description |
|---|---|---|
| keyword |
string |
The keyword that was matched. |
| link_object |
object |
The node (as a ezcontentobjecttreenode object) that encapsulates an object which uses the matched keyword. |
If no match is found, the function will return FALSE.
{def $list=fetch( 'content', 'keyword', hash( alphabet, 'computer', classid, 3 ) )} {foreach $list as $element} {$element.link_object.name|wash} ({$element.keyword|wash}) <br /> {/foreach}
Outputs the names of nodes that encapsulate objects which make use of keywords starting with the string "computer". In addition, the matched keywords are also printed.
{def $list=fetch( 'content', 'keyword', hash( alphabet, 'computer', classid, array( 1, 3 ) ) )}
Only nodes that encapsulate objects of the specified two classes will be fetched.
{def $list=fetch( 'content', 'keyword', hash( alphabet, 'computer', classid, array( 1, 3 ), owner, 14, sort_by, array( 'modified', false() ) ) )}
Only the nodes/objects that are created by the user that has ID number 14 will be included in the result. The nodes will be sorted by the modification time of the objects; the node that encapsulates the most recently modified object will be the first element in the collection.