Custom Fields – Search Form

Posted in: Developer Documentation

This tutorial explains how to insert category dropdown into [adverts_list] search form, in order to complete it some PHP and WordPress API knowledge is required.

The code visible below you should paste either in your current theme functions.php file or create a new plugin and put it there.

Registering Category Field

The first thing we need to do in order to be able to search by category is register / insert the field in search, this can be done easily using adverts_form_load filter, if you want to learn more about this filter and how to modify forms, please see the Forms API doc.

add_filter( 'adverts_form_load', 'search_by_category_form_load' );

/**
 * Adds category dropdown into search form in [adverts_list].
 * 
 * @param array $form Search form scheme
 * @return array Customized search form scheme 
 */
function search_by_category_form_load( $form ) {
    
    if( $form['name'] != 'search' ) {
        return $form;
    }
    $form['field'][] = array(
        "name" => "advert_category",
        "type" => "adverts_field_select",
        "order" => 20,
        "label" => __("Category", "adverts"),
        "max_choices" => 10,
        "options" => array(),
        "options_callback" => "adverts_taxonomies",
        "meta" => array(
            "search_group" => "visible",
            "search_type" => "full" 
        )
    );
    return $form;
}

The search_by_category_form_load() function first checks if currently proccessed form is the [adverts_list] search form, if yes, then it inserts additional dropdown into the form.

Most of the field options (“name”, “type”, “order”, “label”, “max_choices”, “options” and “options_callback”) are described in the Forms API document, if you are not familiar with them refer to this document for more details. Here we will focus on  “meta” propery only as it is unique to search form, the “meta” property has two additional properties

  • search_group (string) – one of “visible” and “hidden”, if you set value to “visible” then the field will always be visible in the form, if on the other and you set it to “hidden” then in the search form you will see additional “Filters …” button, clicking it will show hidden search fields.
    NOTE: right now the “hidden” is not fully implemented, so please use only “visible” for now.
  • search_type (string) – one of “full” and “half”, the difference between them is that “full” will make input take 100% of search box width, while”half” will make the input take only 50% of width. In other words you can have one “full” input per row or 2 “half” inputs per row.

If you go to your page with [adverts_list] shortcode it should look like on the image below.

category-search

Searching By Category

Ok, so now we have the category field in the search form, now we need to write some code which will do the actual search. The easiest way to do it is to use adverts_list_query filter, this is a filter which is executed on $args which will be passed to WP_Query. Basically doing the search by category comes down to modifying WP_Query search params before the search is executed.

In WPAdverts Categories are saved as taxonomies, so in order to search by category we need to add tax_query param, see the code below

add_filter( 'adverts_list_query', 'search_by_category_query' );

/**
 * Adds tax_query param to WP_Query
 * 
 * The tax_query is added only if it is in $_GET['advert_category']
 * 
 * @param array $args WP_Query args
 * @return array Modified WP_Query args
 */
function search_by_category_query( $args ) {
    
    if( ! adverts_request( "advert_category" ) ) {
        return $args;
    }
    
    $args["tax_query"] = array(
        array(
            'taxonomy' => 'advert_category',
            'field'    => 'term_id',
            'terms'    => adverts_request( "advert_category" ),
        ),
    );
    
    return $args;
}

That is pretty much it, from now on you should be able to filter Ads by category. You can similarly add further options to the search, first insert it into Form and then modify WP_Query $args.

If you are having some problems with this tutorial you can see the full source code on GitHub Search By Category page.