Rewrite choices

Finder's strength is that it can provide form elements that allow the user to choose from a list of choices, such as autocomplete textfields, radio buttons, checkboxes, and select lists. Traditionally these choices are sourced automatically by finder through a Views database query that gathers this data from the values that have actually been used on your website, for the field in question. There are now other ways to provide the list of choices (e.g. if this initial database query is too unreasonably slow), but when the finder element configuration Choices style is set to Used values finder will gather choices the traditional way.

The Rewrite choices configuration

The rewrite choices configuration allows a finder administrator to manipulate the list of choices with some custom PHP code. There are two final components to each choice:

Value
This is the key that uniquely identifies the choice in the list of choices. A choice with the same Value as a previous choice will replace the earlier choice. This Value is also what will be submitted to the database to get the finder result or results. In the case of autocompletes this is the prefill text in the textfield after a choice is selected, for most other choices elements it is a hidden value that the user never sees. The Value is almost always a plain string of text.

Display
This is the text or HTML that will be displayed to the user. Select lists only support text (unless you have some cool JavaScript that allows otherwise), but other form elements support HTML. More than one choice can have the same Display. It is also important to note that the Display will be sanitized before being output to the screen, depending on the finder element field's configuration. Click the name of the field in the finder element configuration to change this, as by default many HTML tags are filtered out for security - use your judgement as you don't want some user submitted HTML to give you any surprises and mess up your form or cause security holes. Usually by default the Display is really just a sanitized version of the Value.

The rewrite choices allows you to add PHP code to modify either the Value or the Display. There is one text area for each.

How do I know what I can do with this?

If you enter any code into these areas they must always at minimum return the default $value or $display variable, which ever is appropriate to the setting you've chosen to modify. You can however use some logic to modify $value or $display before returning, and that is the point of these settings.

The first thing to do is debug what information is available to you. If you have the Devel module installed you can use the dpm function. For example to determine what is in the $row variable simply paste this code in:
<?php dpm($row);?>
If you don't have Devel there is another way to do it:
<?php drupal_set_message("<pre>".print_r($row,1)); ?>

Save the finder, and go to the finder form and attempt to use it. For selects/radios/checkboxes you should only have to visit the page to obtain the debug information, for autocompletes you will need to use the autocomplete to get at least one suggestion, and then reload the page to see the debug information (then you will see a debug for each choice).

Note: That if you try to output too much information through these debug techniques, you may not see anything due to limitations in how much your session will store. In these cases you may need to modify your debug code to loop through arrays/objects and only debug the 'keys' and then use those for further debugging, it is a painfully tedious process. You may consider other kinds of debugging like writing output to a file or using the error_log() function.

There are a number of variables available to debug and later use in your rewrite code:

$element - Object containing data about this finder element.
$value - The key value that will be submitted.
$display - The default display value for the choice.
$row - Object containing the result of the database record.
$field - Object containing data about the relevant field.
$delta - The array key of field properties that come as an array.

What data you use to write your PHP logic is up to you, obviously a fair amount of PHP knowledge is required as this is for advanced users that are not satisfied with the default functionality available in finder.

Examples of rewrite code

Autocomplete on node body content, but prefill/submit the title

Create a content finder with an autocomplete element and add the title field and body field to that element.

Open the 'rewrite choices' configuration in the element.

In the 'value' area, add code to debug the $row as shown previously on this page.

Create a node with title "supercalifragilistic" and the body of "expialidocious".

Save the finder.

Go to the finder.

Type "expi" into the autocomplete.

Reload the page. You will see debug info like this:

... (Object) stdClass
node_title (String, 20 characters ) supercalifragilistic
nid (String, 3 characters ) 169
node_language (String, 3 characters ) und
node_created (String, 10 characters ) 1336306990
finder_field_1 (String, 20 characters ) supercalifragilistic
finder_field_2 (String, 14 characters ) expialidocious
finder_field_1_matched (String, 1 characters ) 0
finder_field_2_matched (String, 1 characters ) 1

Now we have a few handy things here... you can access $row->node_title directly (Happy accident that this is the field we're interested in) you can get more info about the node by pulling up the whole node object with $node = node_load($row->nid); and then using whatever data you like, or you can use the value at $row->finder_field_1 which is also the node title. You can do a check to make sure $row->finder_field_1_matched == 0 && $row->finder_field_2_matched == 1 which indicates that the body field matched the user's keywords but the title did not which is the situation we want to affect.

Your particular data may of course differ that's why it is a good idea to do this debugging first.

So now you can concoct your actual rewrite code, for example:

<?php
if ($row->finder_field_1_matched == 0 && $row->finder_field_2_matched == 1) {
  $value = $row->finder_field_1;
}
// Note: always return at the end, after all if-logic to ensure we preserve the default in cases we're not interested in.
return $value;
?>

Set that as the 'rewrite choices' code, and save the finder again.

You should now be able to search for body keywords but prefill the title.

Autocomplete by title, but show node teasers as suggestions

Create a content finder with a single finder element that is an autocomplete with the Content: Title field.

Debug the $row through the 'Rewrite choice' configuration in the 'Display' PHP area, as previously explained in this tutorial. You can of course debug other available variables.

Ultimately you will probably come up with some code like this to put in the 'Display' PHP area:

<?php
  $node = node_load($row->nid);
  $teaser = node_view($node, 'teaser');
  return $teaser;
?>

Remember: Because you are now outputting HTML you will need to reconsider the 'sanitization' configuration (click on the field name in the element config) so it permits HTML code.

You can get more creative with it and output particular stuff from the $node with your own HTML and such, up to you.

You'll notice the autocomplete suggestions look pretty ugly. You'll need to tame them with some CSS. Add some CSS to your theme, wherever you normally do your CSS stuff. The basic CSS you need is like so:

   #autocomplete li.selected {
     background: #eee;
     color: inherit;
   }
   #autocomplete li {
     white-space: normal;
     margin: 0;
   }
   #autocomplete ul.links,
   #autocomplete ul.links li {
     background: none;
   }
   #autocomplete p {
     margin: 0;
   }

But, you probably won't want to affect every autocomplete on your website, so you can prefix those CSS selectors with something to restrict what you affect. This is pretty easy to determine with Firebug or the Chrome Inspector, if you don't know about those... look them up now and save yourself the headaches.

The finder is usually wrapped in something like "div#finder-page-finder_name-wrapper" which is the 'page' output for the finder with finder id 'finder_name'. A more generic wrapper for the finder is found inside this "div.finder-finder_name" which simply denotes output for finder 'finder_name'. To select a particular element within the finder; use the ID of the div with class "form-item" that wraps the element.

From there it's up to you what to do. But be warned; it isn't easy styling this thing because Firebug and the Chrome Inspector don't work so well on the autocomplete suggestion popup - it keeps disappearing. If that drives you mad, you can find this line in the JavaScript and comment it out: $(popup).fadeOut('fast', function() { $(popup).remove(); }); - in the following file in the Finder module: plugins/element_handler/autocomplete.js