Muddling, meddling and getting it right with Apache Solr

Working with Apachesolr can be an oscillation between 'aha!' and 'huh?' moments - in turns impressed by the code (Thanks Robert, Peter, James, Jacob and the others) and baffled by the documentation.

Some kind souls had left some helpful leads (like this, this, this, this, etc.), others had contributed some excellent code (like the autocomplete enhancement).
But now that our project is over and I have some time to think (plus we're gathering together some useful content for this new website), it's time to write down what we did, what we learnt and how to avoid some of the mistakes we made.

The primary reference for this article is Guías Clarín - a big directory of businesses. If you have javascript turned on, the advertising slows down the page load quite significantly, but the basic search functionality is blindingly fast and really rather good. (More about the project in the right panel, related content).

First problem

Two co-ordinated search boxes.

What we wanted to do: Find out not just 'what' are you searching for, but 'where'.
How we did it: There may well be a better way to do this, but here's our solution. Please do leave any suggestions or comments below.
We threw away the default search box, creating a form with two fields.
(Our module here is called 'guia_solr'. Just so you know)

/**
 * Implementation of hook_form().
 */
function guia_solr_search_form($form_state) {
    // Get previous search terms from url.
    $defaults = guia_solr_get_defaults();
    $form['what'] = array(
          '#type' => 'textfield',
          '#size' => 20,
          '#default_value' => $defaults['what'],
    );
    $form['where'] = array(
          '#type' => 'textfield',
          '#size' => 20,
          '#default_value' => $defaults['where'],
    );
    $form['submit'] = array(
          '#type' => 'submit',
          '#weight' => 10,
          '#value' => t('Search'),
    );
    return $form;
}
 
//Validation checks that a 'What' value is given, or returns the form with a message.
 
function guia_solr_search_form_submit($form, &$form_state) {
    $what = strtolower(trim($form_state['values']['what']));
    $where = strtolower(trim($form_state['values']['where']));
    // Need to check there's no other form redirection going on.
    if (isset($_REQUEST['destination'])) {
        unset($_REQUEST['destination']);
    }
    if (isset($_REQUEST['edit']['destination'])) {
        unset($_REQUEST['edit']['destination']);
    }
    // Choose a path that doesn't conflict with Drupal's own 'search'.
    $path = 'find/';
    if ($where == '') {
        $form_state['redirect'] = $path . $what;
    }
    else {
        $form_state['redirect'] = $path . $what . '|' . $where;
    }
}

Nothing too complex there, though the autocomplete functionality has been left out, which involves some extra considerations (only returning results for the appropriate field, responding intuitively to the 'enter' key as well as the submit button, etc).

We then have a query dispatched to the path 'find/what|where'.

The next post handles this path, and our second challenge, 'Really Clean URLs'.