.. index:: Macro function;fn.filter_by_rule

Rule filter functions
---------------------


The "filter by rule" function returns a list of resource instance data for a given model type. 
The schema of the model type in question must define a ``rules`` object of the form:

::

  {
     'rules': {
            'hierarchy_types': [<list of data/HierarchyNodeType business keys>]
      }
  }

The model ``data/Role`` is one example of such a model type. Filtering is applied 
using the current hierarchy context or else based on an explicit hierarchy type name. 

Macro format: 

::

  {{ fn.filter_by_rule <rule name>,
                      <model type>,
                      <direction>,
                      <attribute path to return>,
                      <hierarchy type name> }}
    
Argument descriptions:

<rule name>: 
   The name of the rule being used to filter results. Supported values: ``hierarchy_types``

<model type>:
   The model type of the instances to be filtered.

<direction>: 
   The search direction of the results. Possible values are:
 
     * ``all`` - search at current hierarchy, ancestors, and descendants.
     * ``up`` - search at current hierarchy and ancestors.
     * ``down`` - search at current hierarchy and descendants.
     * ``local`` - search at current hierarchy only.

<attribute path to return>: [optional] 
   The path dot (.) delimited path to a single attribute to return.

   * If not specified the returned result will contain a list of objects.
   * If specified the returned result will contain a list the given attribute.
   * Must be "null" if this field is not required, while <hierarchy type name> is supplied.

<hierarchy type name>: [optional] 
   The name of the hierarchy type to filter by. This will be looked up from the 
   current hierarchy going up.

Examples: 

::

   {{ fn.filter_by_rule hierarchy_types,data/Role,up,name,Customer }}

Returns all the names of the roles that are permitted at "Customer" hierarchy type. 
Lookup is done from the current hierarchy upwards.

::

   {{ fn.filter_by_rule hierarchy_types,data/Role,up,null,Customer }}

Returns full instance data of the roles that are permitted at "Customer" 
hierarchy type. Lookup is done from the current hierarchy upwards.

::

   {{ fn.filter_by_rule hierarchy_types,data/Role,up,name }}

Returns all the names of the roles that are permitted at the hierarchy 
type of the current hierarchy context. Lookup is done from the current hierarchy upwards.

:: 

   {{ fn.filter_by_rule hierarchy_types,data/Role,up }}

Returns full instance data of the roles that are permitted at the hierarchy 
type of the current hierarchy context. Lookup is done from the current hierarchy upwards.