.. _dropdown-filters:

.. rst-class:: chapter-with-expand


Dropdown Filters
----------------

.. _19.2.1|VOSS-632:


Administrators with access to the **Dropdown Filters** menu can manage the items
available in dropdown lists on input forms. A filter would typically be used to
define a shorter dropdown list.

Filters can be added, removed, modified and two existing filters can also be merged
to define a new filter.

The Dropdown Filter list macro name that is generated starts with ``DDF__`` and is
of the format (dots and slashes replaced by underscores):

``DDF__<target model type> _<target model name>_<target field>``

This is also the name shown in the **Dropdown Filters** list view at the hierarchy
at which is was created.


.. _Add-a-Dropdown-Filter:

Add a Dropdown Filter
.....................

1. Navigate to the required hierarchy.
#. Select the **Dropdown Filters** menu and click **Add**.   
#. Choose **Create a Dropdown Filter** From the **Select a Dropdown Filter Action**
   dropdown list.
#. Choose the **Target Model** and **Target Field** names to which the filter is
   to be applied. 
   
   This is the dropdown field on an input form on the Admin Portal. Click **Help** on the
   input form to see the names.
#. Identify the associated **Model Type** and **Dropdown Field** of the **Dropdown
   Filter specifications**.
  
   This can differ from the form names. Click **Help** on the input form to verify.
#. Set up the **Filter Fields**. Compare a **Filter Field** to a **Filter Field Value**:

   * contained in or not contained in
   * equal or not equal

   Note that:
  
   * The **Filter Field** can differ from the **Target Field**. In other
     words, the dropdown list can be filtered according a filter applied to *another* 
     field that belongs to the **Model Type**.
   * The **Filter Field value** can also take the *name* of a named macro that
     resolves to a value, for example: ``macro.SITENAME``.  
   * If the same **Filter Field** is used more than once, these filters will be merged,
     in other words, the *combined* filters on the field apply.
#. Add **Additional Parameters** to the filter:

   * direction:hierarchy direction for search: 
     [up|down|local|parent|below|above] 
     (``below`` and ``above`` exclude current hierarchy)
   * device: device name
   * ndl: network device list that the device belongs to
   * limit: number of results
   * skip: start number of results - can be used for paging
   * title: character or regular expression: only return values matching its value

   For details and examples, refer to the topics on macro syntax in the Advanced Configuration Guide.

#. Click **Save**. A dropdown filter is created.

   This filter is a named list macro that will be added to the GUI Rule which is
   in place at the selected hierarchy for the **Target Field** on the Admin Portal
   input form of the selected **Target Model Name**.

When a created dropdown filter is opened, the macro is shown in the **Macro**
field at the bottom of the form. Users who have menu access to the list of named macros
can also see the dropdown filter macros by filtering the list by name starting with ``DDF__``.


.. _Example-of-a-Dropdown-Filter:

Example of a Dropdown Filter
............................

Consider the filter:

* **Target Model Name**: ``relation/LineRelation``
* **Target Field**: ``callForwardAll.callingSearchSpaceName``
* **Model Type**: ``device/cucm/Css``
* **Dropdown Field**: ``name``
* **Filter Field**: ``name``
* **Filter Condition**: ``Contains``
* **Filter Field Value**: ``Cu2``
* **Additional Parameter**: **Parameter Title**: ``Direction``
* **Additional Parameter**: **Parameter value**: ``up``

The list macro that is created applies to the GUI rule for the input field
``callForwardAll.callingSearchSpaceName`` of the input form for ``relation/LineRelation``
at the selected hierarchy.
The list macro would then be:

::

   {# device/cucm/Css | name /Cu2/i | direction: up #}

If you have access to the Macro Evaluator, you can test this macro.
Also refer to the topic on Macro Syntax in the Advanced Configuration Guide
for more details.

In the **Dropdown Filters** list view at the hierarchy, the **Filter Name** shows as:

``DDF__relation_LineRelationTarget_callForwardAll_callingSearchSpaceName``



.. _Merged-Dropdown-Filters:

Merged Dropdown Filters
.......................


Two existing dropdown filters can be merged to create a new dropdown filter.
The merged filter is a dropdown list that uniquely combines the lists from the
two dropdown filters.


.. _Merge-Dropdown-Filters:

Merge Dropdown Filters
......................

1. Navigate to the required hierarchy.
#. Select the **Dropdown Filters** menu.  
   
   Check that the two dropdown filters that you want to merge are showing in the
   list view at the hierarchy. Otherwise, add the dropdown filters.

   .. note:
   
      If you have access to the Macro Evaluator, you can evaluate the macros of
      the filters and inspect the filtered list results of each macro that you
      wish to merge.

#. Choose **Merge Existing Dropdown Filters** from the **Select a Dropdown Filter
   Action** dropdown list.
#. Choose the **Target Model** and **Target Field** names to which the filter is
   to be applied. 
#. Choose the two dropdown filters from the **Dropdown Filters to merge** form.   
#. Click **Save**. A merged dropdown filter is created. 

.. note::   

   Only two filters can be merged. 

   If you wish to merge more than two dropdown filters, first create a
   merged filter of each filter pair and select it to be merged.

When a created merged dropdown filter is opened, the macro is shown in the **Macro**
field at the bottom of the form.
The macro uses the ``fn.list_extend_no_dup`` macro function to uniquely merge the 
two dropdown filter lists. The macro syntax is of the format

::

   {{ fn.list_extend_no_dup macro.DDF__<filter name 1>, macro.DDF__<filter name 2> }}

Refer to the topic on Macro Syntax and List Functions in the Advanced Configuration
Guide for more details.