This guide explains how the standard property list filters are rendered, how clicks are handled, and how to add or modify dropdowns that appear inside the .listing_filters_head wrapper. Code references point to the relevant templates, PHP helpers, and JavaScript handlers in the theme.

Where the filter head is rendered

• The main filter header (used by property list pages) is assembled in templates/properties_list_templates/property_list_filters.php#L187-L213. It outputs the <div class="listing_filters_head"> wrapper, adds the hidden #page_idx, and calls wpestate_build_dropdown_for_filters() for each dropdown (types, categories, counties, cities, areas, optional status/features, and order-by).
• Taxonomy/result pages reuse the same structure in templates/properties_list_templates/filters_templates/property_list_filters_taxonomy_normal_map_core.php#L96-L136, which pre-populates the current term label/value before rendering the dropdowns and the order-by control wpresidence_display_orderby_dropdown.
• The dropdown markup itself is generated by wpestate_build_dropdown_for_filters() in functions.php#L3054-L3087, which wraps a toggle button (.filter_menu_trigger) and an unordered list containing the provided <li> options. The wrapper class wpresidence_wrap_<dropdown_id> is added automatically so you can target each filter in CSS/JS.

How clicks are handled

• All list items inside .listing_filters_head are wired in js/ajaxcalls.js#L1384-L1394. When a <li> is clicked, the handler updates the button text, sets the data-value on the button, mirrors the value into a hidden input (if present), and calls wpestate_start_filtering(1) to reload results.
• Advanced search headers (.adv_listing_filters_head) follow the same pattern but trigger an AJAX request to rebuild the listing container, as shown in the same file at js/ajaxcalls.js#L1405-L1434.

Adding a brand-new filter dropdown

1. Prepare the option list: Build an HTML string of <li role="presentation" data-value="...">Label</li> items. You can follow the existing select-list helpers used in property_list_filters.php (e.g., wpestate_get_action_select_list, wpestate_get_category_select_list, etc.) for structure. Make sure each item carries its value in data-value so the JavaScript handler can pick it up.
2. Render the dropdown: Call wpestate_build_dropdown_for_filters('a_filter_<yourkey>', $selected_value, $label, $your_select_list') inside the filter head template. The first argument drives the DOM IDs/classes (id="a_filter_<yourkey>", wrapper class wpresidence_wrap_a_filter_<yourkey>), so choose a unique key that won’t collide with existing filters. Place the call alongside the other dropdowns near lines 187-213 in property_list_filters.php or in the taxonomy variant at lines 96-105.
3. Pass the selection into the query: If your new filter should affect the property query, ensure the backend code that builds the listing query reads the submitted value. The JS click handler mirrors the selected data-value into a hidden input and triggers wpestate_start_filtering(1); you need to extend the PHP that consumes the request (mirroring how existing filters are read) so your new parameter is forwarded to the query arguments.

Modifying existing filters

• Rename labels or reorder dropdowns: Edit the sequence of wpestate_build_dropdown_for_filters() calls in property_list_filters.php (lines 187-213) or the taxonomy template (lines 96-105) to change labels or ordering.
• Change option sets: Update the select-list helper that feeds the dropdown (e.g., wpestate_get_action_select_list, wpestate_get_category_select_list) or adjust the taxonomy terms they pull from. These helpers are assembled just above the rendering block in property_list_filters.php#L174-L180 and the taxonomy template (#L87-L93).
• Parent/child relationships: If you need dependent filters (e.g., county → city → area), mirror the existing data-parentcounty or data-parentcity attributes used in the generated <li> items so your JS logic can constrain children correctly.

Layout and styling hooks

Each dropdown gets shared classes (.dropdown, .listing_filter_select, .wpresidence_filters_dropdown) plus a specific wrapper wpresidence_wrap_<dropdown_id>, making it easy to add custom styling in your SCSS alongside the existing filter-head styles.