Used for finding nodes that match certain criterias.

About¶ ↑

This extension class is used for finding nodes that match certain criterias (all nodes are used if no filter options are specified) when calling the find method. There are some built-in filters but one can also provide custom filters via add_filter_module.

The found nodes are either returned in a flat list or hierarchical in nested lists (if a node has no child nodes, only the node itself is used; otherwise a two element array containing the node and child nodes is used). Sorting, limiting the number of returned nodes and using an offset are also possible.

Note that results are cached in the volatile cache of the Cache instance!

Finder options¶ ↑

A complete list of the supported finder options can be found in the user documentation! Note that there may also be other 3rd party node filters available if you are using extension bundles!

Implementing a filter module¶ ↑

Implementing a filter module is very easy. Just create a module that contains your filter methods and tell the NodeFinder object about it using the add_filter_module method. A filter method needs to take three arguments: the Result stucture, the reference node and the filter value.

The result.nodes accessor contains the array of nodes that should be manipulated in-place.

If a filter uses the reference node, it has to tell the node finder about it to allow proper caching:

• If the node's language property is used, result.lang_used has to be set to true.

• If the node's hierarchy level is used, result.level_used has to be set to true.

• If the node's parent is used, result.parent_node_used has to be set to true.

• In all other cases, result.ref_node_used has to be set to true

Here is a sample filter module which provides the ability to filter nodes based on the meta information key category. The category key contains an array with one or more categories. The value for this category filter is one or more strings and the filter returns those nodes that contain at least one specified category.

module CategoryFilter

  def filter_on_category(result, ref_node, categories)
    categories = [categories].flatten # needed in case categories is a string
    result.nodes.select! {|n| categories.any? {|c| n['category'].include?(c)}}
  end

end

website.ext.node_finder.add_filter_module(CategoryFilter, category: 'filter_on_category')