search
Summary
Fetches nodes containing data that match a certain criteria.Usage
fetch( content, search, hash( text, text, [ offset, offset, ] [ limit, limit, ] [ section_id, id, ] [ subtree_array, array, ] [ publish_timestamp, time, ] [ publish_date, date, ] [ class_id, id, ] [ class_attribute_id, id, ] [ sort_by, sort_by, ] [ limitation, limitation, ] [ ignore_visibility, ignore_visibility, ] ) )
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| text | string | The text that should be matched. | Yes. |
| subtree_array | mixed | Array node ID number under which the system should search. | No. |
| offset | integer | The offset to start at. | No. |
| limit | integer | The number of nodes that should be returned. | No. |
| publish_timestamp | integer | Only search objects with the specified publishing date/time (as a UNIX timestamp). | No. |
| publish_date | integer | Only search objects published during the last day / week / month / three months / one year. | No. |
| section_id | integer | Only match objects that are in this section. | No. |
| class_id | integer | Only match objects that are instances of this class. This parameter can also be an array of class ID numbers. | No. |
| class_attribute_id | integer | Only search within this attribute. This parameter can also be an array of attribute ID numbers. | No. |
| sort_by | mixed | Sort the result. See description below. | No. |
| limitation | array | Limitation array (emtpy array = access override). | No. |
| ignore_visibility | boolean | Makes it possible to get hidden nodes. | No. |
Returns
An array of hashes (see below) or FALSE.
Description
This function will perform a search and it will return the hits that the current user has read access to. The function returns an array of hashes. The hashes consist of the following elements:
| SearchResult |
array |
An array of the nodes (as ezcontentobjecttreenode objects) that matched the search conditions. |
| SearchCount |
integer |
The total number of nodes that matched the search conditions. |
| StopWordArray |
array |
An array of strings containing words that were excluded from the search. |
Sorting
The "sort_by" parameter makes it possible to sort the result in different ways. This parameter behaves exactly in the same way as it does for the "list" function. Please refer to the documentation page of the "list" function for a complete explanation of this parameter.
Searching by the date of publishing
The "publish_date" parameter makes it possible to search objects published during the specified period. The following table reveals the possible values of this parameter.
| 1 |
one day |
| 2 |
one week |
| 3 |
one month |
| 4 |
three months |
| 5 |
one year |
The "publish_timestamp" parameter makes it possible to search objects with the specified publishing date/time. This value must be a UNIX timestamp. You can also use an array of two elements in order to search withing the given range.
Please note that you can not use both "publish_timestamp" and "publish_date" at the same time. If you use "publish_timestamp" then "publish_date" will be ignored.
Access override
The "limitation" parameter makes it possible to instruct the system to use an alternate set of access limitations instead of the ones that belong to the current user. This is typically useful when there is a need to match and return nodes that the current user does not have access to. All permission checking can be skipped by providing an empty array. It is also possible to provide arrays that define access limitations of other users and/or custom sets of limitations. Note that this is for advanced/experienced users. You'll have to look in the source code of the kernel for details related to the format of this array.
Visibility override
The "ignore_visibility" parameter makes it possible to allow the search function to get hidden nodes. It can be set to either "true()" or "false()" (default). If set to "true()", the search engine will ignore the visibility flags of nodes and thus the result will contain all kinds of nodes regardless if they are hidden or not. In other words, this parameter overrides the "ShowHiddenNodes" configuration directive for a specific search operation in a template.
Examples
Example 1
{def $search=fetch( 'content', 'search', hash( 'text', 'example', 'class_id', array( '2', '5' ) ) )} The search returned {$search.SearchCount} matches. <br /> {foreach $search.SearchResult as $matched_node} {$matched_node.name|wash} <br /> {/foreach}
Outputs the names of all nodes which encapsulte objects of classes 2 and 5 containing the word "example".
Example 2
{def $search=fetch( 'content', 'search', hash( 'text', 'example', 'publish_timestamp', array( '1033920746', '1033920789' ) ) )} The search returned {$search.SearchCount} matches. <br /> {foreach $search.SearchResult as $matched_node} {$matched_node.name|wash} <br /> {/foreach}
Outputs the names of all nodes which encapsulte objects published between the specified date/time values.
Balazs Halasy (06/02/2004 12:12 pm)
Balazs Halasy (09/04/2007 12:05 pm)
Comments