.. _dropdown-filters: Drop-down filters ------------------ .. _19.2.1|VOSS-632: .. tip:: :ref:`use-action-search-to-navigate-automate` Overview ......... Administrators with access to the **Dropdown Filters** page can manage the items available in drop-down lists on input forms. A filter would typically be used to define a shorter drop-down 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__ __`` 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 drop-down filter ....................... 1. Navigate to the required hierarchy. #. Go to the **Dropdown Filters** page, then click the Plus icon (+) to add a new record. #. At **Select a Dropdown Filter action**, select **Create a Dropdown Filter**. #. Select a target model name and target field name to which the filter is to be applied. This is the drop-down 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**. .. note:: 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:: * The **Filter Field** can differ from the **Target Field**, that is, the drop-down 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, that is, 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 drop-down 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 opening a drop-down filter, 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 drop-down filter macros by filtering the list by name starting with ``DDF__``. .. _Example-of-a-Dropdown-Filter: Drop-down filter example ............................ 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 drop-down filters .......................... Two existing drop-down filters can be merged to create a new dropdown filter. The merged filter is a drop-down list that uniquely combines the lists from the two drop-down filters. .. _Merge-Dropdown-Filters: Merge drop-down filters ....................... 1. Navigate to the required hierarchy. #. Go to the **Dropdown Filters** page. Check that the two drop-down filters that you want to merge are showing in the list view at the hierarchy. Otherwise, add the drop-down 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** drop-down list. #. Choose the **Target Model** and **Target Field** names to which the filter is to be applied. #. Choose the two drop-down filters from the **Dropdown Filters to merge** form. #. Click **Save**. A merged drop-down filter is created. .. note:: Only two filters can be merged. To merge more than two drop-down filters, first create a merged filter of each filter pair and select it to be merged. When a created merged drop-down 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 drop-down filter lists. The macro syntax is of the format :: {{ fn.list_extend_no_dup macro.DDF__, macro.DDF__ }} Refer to the topic on Macro Syntax and List Functions in the Advanced Configuration Guide for more details.