Description

Facetious lets you add a faceted – often called an ‘advanced’ – search form to your WordPress website. It comes with a ready-to-use sidebar widget, plus a number of implementation options for developers.

A Facetious form can include dropdown lists of:

• Taxonomy terms (tags, categories, and custom taxonomies)
• Months
• Plus a conventional search input box

You can also restrict searches by post type (singular), if you so desire.

Additionally, Facetious introduces an extra ‘pretty permalink’ structure around search queries, which may help your site performance if you’re using a caching plugin like WP Super Cache. Also, they look a heck of a lot friendlier than ?s=polly&post_type=pet&category=bird. (You don’t even have to display a faceted search form on your site to benefit from these, by the way).

Please note – Facetious isn’t a replacement search engine; it helps you construct the search query, but then it’s over to WordPress to run the actual search.

About

Facetious is a product of Code For The People Ltd, and is based on work done during 2012 on behalf of several UK public sector clients, among them:

• The Commission on Devolution in Wales
• The National Audit Office; and
• The Department for Culture, Media and Sport through its Government Olympic Communication site

… which is why we’re keen to offer it for wider public use.

Fork me on GitHub!

Usage

The simplest way to add a Facetious search form is to add the Facetious widget to your sidebar. You’ll see a complete list of options so you can choose which fields to include in your search form.

Advanced Usage

Developers can use a template function to output a Facetious search form and have complete control over the form and its fields, such as text labels, class names, etc.

The main template function for outputting a Facetious search form is facetious( $args ). If you want to ensure the site doesn’t break if the Facetious plugin is deactivated, you can use do_action( 'facetious', $args ); instead.

‘$args’ is an array of arguments thus:

• submit – string – The text for the submit button.
• echo – boolean – Whether to echo the form out or not.
• class – string – The class name for the form.
• id – string – The ID attribute for the form.
• fields – array – A list of fields to show in the form. See below.

Each item in the ‘fields’ array can be either:

• A string name of a taxonomy
• An array of details for the field (see below)
• One of s, m or pt for the keyword search input, month dropdown and post type dropdown respectively

For each field specified as an array you can specify:

• label – string – The descriptive text for this field. Defaults to the name of the taxonomy, or ‘All types’ for post types..
• class – string – The class name for the field.
• id – string – The ID attribute for the field.
• all – string – The “All items” text for this field. Defaults to the ‘all_items’ label of the taxonomy.
• options – array – For a taxonomy provide an array with the term slug as the key and the term name as the value, e.g. array( 'term-1' => 'Term 1', 'term-2' => 'Term 2' );, for post type supply an array of post type names.

Example 1:

do_action( 'facetious', array(
    'submit' => 'Search',
    'fields' => array(
        's',
        'category',
        'custom_tax_1',
        'custom_tax_2'
    )
) );

Example 2:

do_action( 'facetious', array(
    'submit' => 'Search',
    'fields' => array(
        's',
        'custom_tax_1' => array(
            'label' => 'Select an option',
            'class' => 'my_tax_class',
            'id'    => 'my_tax_id',
            'all'   => 'All terms'
        )
        'custom_tax_2',
        'm'
    )
) );