; $Id: DEVELOPERS.txt,v 1.3 2010/03/14 13:39:18 pounard Exp $

Notes about Solace API
======================

This module is a Solr query constructor. It handles an AJAX filters form (that
is reusable for submodules). Filters list can be saved into database for
reusability, if saved in database it also provides caching for Solr query
construction. It gives submodules a set of hooks to define their own filters
that can be used withing this form, it also gives a 'context' definition ability
so the core filter form is able to display filtered list of filters depending on
the given context.

This module's codename was originally "Assistant API". You'll see a lot of
comments and inline documentation that refers to this name.

Heavy usage of hooks
====================

Main module, Solace API gives us hooks defined in assistant_api.api.php. All
submodules will use those hooks instead of drupal defined ones.

Invoking the filter form in your module
=======================================

The goal of this API module is to give developers the chance to spawn the
filters form anywhere they need it, and get back easily the results.

Here is a simple method:
<?php
/**
 * This is our menu callback, it can be any page or page sub part.
 * This example will return you a form without the 'preview' or 'save'
 * options.
 * To ensure those two options, you'll need to define your own context
 * class, see Solace Node Reference module for a complete sample.
 */
function my_page() {
  // This will create a default context
  $context = assistant_api_context_create('my_context_name');
  // Return the new form
  return assistant_api_filters_form_build($context);
}
?>

To see more examples, consult the 'assistant_ref' (Solace Node Reference) and
the assistant_search (Solace Search) module implementations.

What is a context
=================

A context is a simple class definition, overriding the Assistant_ContextAbstract
provided class.
A context will define a set of function that will alter the form's behavior,
that will allow more token replacements, and can store some data for you in
order to get it back at SolR query construction time in order to alter new
SolR built SolR query.

Token and context
=================

Filters can use token in every 'textfield' typed form element defined by any
custom filter. Per default, the only token type that can be used will be the
'global' site wide tokens default provided by the token module.

In order to use more token types, you need to create your own custom context
implementation, by overriding the getAllowedTokenTypes() public method to
return all context types your module supports.

The context implementation must be able to do the token replacements, this
means that the token $object variable, used in token_replace() method must
be provided by the context, by the _getTokenObjectForType() method of you
custom context implementation.

Notes about unit tests
======================

Currently, unit testing is not finished yet. It covers a minor part of the
central API. Some latest changes may affect their results, do not rely on it
right now.
