$Id: README.txt,v 1.2 2009/10/16 22:37:10 jpmckinney Exp $

-- SUMMARY --

The Apache Solr AJAX module AJAXifies the apachesolr module.

For a full description of the module, visit the project page:
  http://drupal.org/project/apachesolr_ajax

To submit bug reports and feature suggestions, or to track changes:
  http://drupal.org/project/issues/apachesolr_ajax

This module acts as glue between the apachesolr Drupal module and the AJAX Solr
JavaScript library. This module's documentation will not go into how to write
AJAX Solr widgets in JavaScript. Please consult the documentation for AJAX Solr
for more information on how to create your own widgets:
  http://evolvingweb.github.com/ajax-solr


-- REQUIREMENTS --

The apachesolr_search and js_theming modules and their dependencies must be
enabled, and the apachesolr module must be configured. Consult the apachesolr
project page for more information:
  http://drupal.org/project/apachesolr


-- INSTALLATION --

* Install as usual, see http://drupal.org/node/70151 for further information.

* Install AJAX Solr into the apachesolr_ajax directory. AJAX Solr is found at
  http://evolvingweb.github.com/ajax-solr in both zip and tar format. Unzip/
  Untar the archive in the apachesolr_ajax directory, and rename the directory
  it extracts to ajaxsolr.

  Example, using curl:

    cd sites/all/modules/apachesolr_ajax
    curl -L -o ajaxsolr.tar.gz http://github.com/evolvingweb/ajax-solr/tarball/master
    tar xvf ajaxsolr.tar.gz
    mv evolvingweb-ajax-solr-* ajaxsolr

  Example, using wget:

    cd sites/all/modules/apachesolr_ajax
    wget -O ajaxsolr.tar.gz http://github.com/evolvingweb/ajax-solr/tarball/master
    tar xvf ajaxsolr.tar.gz
    mv evolvingweb-ajax-solr-* ajaxsolr


-- CONFIGURATION --

* (Optional) Configure user permissions in Administer >> User management >>
  Permissions >> search module:

  - administer search

    Users in roles with the "administer search" permission will be able to
    configure the Apache Solr AJAX module.

* (Optional) Configure Apache Solr AJAX settings in Administer >> Site
  Configuration >> Apache Solr AJAX. Here, you may help secure the Solr server
  and customize the AJAX Solr widgets.


-- DEVELOPERS --

Exposed hooks:

hook_apachesolr_ajax_init();

  Invoked by apachesolr_ajax_search_view() immediately before performing the
  search and rendering the page. Typically, modules implementing AJAX Solr
  widgets will use this hook to add the widget's JavaScript and CSS files,
  using drupal_add_js() and drupal_add_css().

  Example:

    function my_module_apachesolr_ajax_init() {
      $module_path = drupal_get_path('module', 'my_module');
      drupal_add_js($module_path .'/MyWidget.js');
      drupal_add_js($module_path .'/my_module.css');
    }

hook_apachesolr_ajax_manager_data_alter(&$data);

  Allows a module to change the class of the AJAX Solr manager, if that module
  is implementing its own manager, or change the public fields of the manager.
  Visit the following page for the list of public fields:
    http://evolvingweb.github.com/ajax-solr/docs/symbols/AjaxSolr.AbstractManager.html

  Example:

    function my_module_apachesolr_ajax_manager_data_alter(&$data) {
      $data['managerclass'] = 'MyManager';
    }

hook_apachesolr_ajax_widget_data();

  A widget is configured for each apachesolr-enabled facet and for each major
  UI block: the free text search field, search strategy, sorting, results, and
  pager. If a module wants to configure a widget for a new UI block or for an
  unconfigured facet, that module should use this hook to configure that widget.
  Configuring a widget involves settings its class and required public fields.
  Visit the AJAX Solr docs for the list of public fields that each AJAX Solr
  widget exposes (note that other widgets may expose their own public fields):
    http://evolvingweb.github.com/ajax-solr/docs/index.html

  Example, for an unconfigured facet:

    function my_module_apachesolr_ajax_widget_data() {
      $data['ss_starts_with'] = array(
        'id' => 'ss_starts_with',
        'module' => 'my_module',
        'widgetclass' => 'MyWidget',
        'field' => 'ss_starts_with',
      );
      return $data;
    }

hook_apachesolr_ajax_widget_data_alter(&$data);

  Allows a module to change the configuration of the widgets. A widget is
  configured for each apachesolr-enabled facet and for each major UI block: the
  free text search field, search strategy, sorting, results, and pager. The
  module may change the class of a widget, if the module is implementing a
  substitute widget, or change the public fields of a widget. Visit the AJAX
  Solr docs for the list of public fields that each AJAX Solr widget exposes
  (note that other widgets may expose their own public fields):
    http://evolvingweb.github.com/ajax-solr/docs/index.html

  Example:

    function my_module_apachesolr_ajax_widget_data_alter(&$data) {
      $data['result']['widgetclass'] = 'MyResultWidget';
    }

hook_apachesolr_ajax_human_field_data();

  // not yet documented

hook_apachesolr_ajax_human_field_data_alter(&$data);

  // not yet documented


-- THEMERS --

This module uses Drupal's JavaScript theming mechanism: Drupal.theme. It
defines its theme functions in the Drupal.theme.prototype namespace. For
example, the following code defines the theme function "search_result":

  Drupal.theme.prototype.search_result = function (vars) {
    output = ...
    ...
    return output;
  }

To override a theme function provided by this module, define your overriding
theme function in the Drupal.theme namespace. For example, to override
the theme function "search_result":

  Drupal.theme.search_result = function (vars) {
    output = ...
    ...
    return output;
  }

We recommend you write all your theme functions in the Drupal.theme namespace,
so that there is never a conflict with the namespace used by this module.

This module defines some Drupal functions useful to theming, including
"formatDate", "searchHelp", and "truncateUtf8". More Drupal functions are
defined by the js_theming module:
  http://drupal.org/project/js_theming

This module defines its theme functions in *.theme.js files. We recommend you
follow this convention in your own modules/themes.


-- GOTCHAS --

If you have written any hook_apachesolr_search_result_alter() or
hook_apachesolr_process_results() functions while developing your site with the
apachesolr module, you will have to duplicate the functionality of the functions
you've written in a custom results widget, as this module won't run those
functions. See the documentation in ResultWidget.js for more information.


-- CONTACT --

Current maintainers:
* James McKinney (jpmckinney) - http://drupal.org/user/472460
* Logan Smyth (loganfsmyth) - http://drupal.org/user/571728

This project has been sponsored by:
* Evolving Web
  Drupal Web Design + Development in Montréal. Visit http://evolvingweb.ca for
  more information.
