/* $Id: README.txt,v 1.1.2.1.2.15 2009-04-03 15:01:11 pwolanin Exp $ */

This module integrates Drupal with the Apache Solr search platform. Solr search
can be used as a replacement for core content search and boasts both extra
features and better performance. Among the extra features is the ability to have
faceted search on facets ranging from content author to taxonomy to arbitrary
CCK fields.

The module comes with a schema.xml and solrconfig.xml file which should be used
in your Solr installation.

This module depends on the search framework in core. However, you may not want
the core searches and only want Solr search. If that is the case, you want to
use the Core Searches module in tandem with this module.


Installation
------------

Prerequisite: Java 5 or higher (a.k.a. 1.5.x).  PHP 5.1.4 or higher.

Those with PHP < 5.2.0 must install the PECL json module or download
the Json code from the Zend Framework (see below).

Install the Apache Solr Drupal module as you would any Drupal module.

Before enabling it, you must also do the following:

Get the PHP library from the external project. The project is
found at:  http://code.google.com/p/solr-php-client/
From the apachesolr module directory, run this command:

svn checkout -r6 http://solr-php-client.googlecode.com/svn/trunk/ SolrPhpClient

Note that revision 6 is the currently tested and suggested revision. 
Make sure that the final directory is named SolrPhpClient under the apachesolr
module directory.  Note: the 2009-03-11 version of the library from the 
googlecode page is r5 and will not work with beta6+.

Download Solr trunk (candidate 1.4.x build) from a nightly build or build it
from svn.  http://people.apache.org/builds/lucene/solr/nightly/

Once Solr 1.4 is released, you will be able to download from:
http://www.apache.org/dyn/closer.cgi/lucene/solr/

Unpack the tarball somewhere not visible to the web (not in your apache docroot
and not inside of your drupal directory).

The Solr download comes with an example application that you can use for
testing, development, and even for smaller production sites. This
application is found at apache-solr-nightly/example.

Move apache-solr-nightly/example/solr/conf/schema.xml and rename it to
something like schema.bak. Then move the schema.xml that comes with the
ApacheSolr Drupal module to take its place.

Similarly, move apache-solr-nightly/example/solr/conf/solrconfig.xml and rename
it like solrconfig.bak. Then move the solrconfig.xml that comes with the
ApacheSolr Drupal module to take its place.

Now start the solr application by opening a shell, changing directory to
apache-solr-nightly/example, and executing the command java -jar start.jar

Test that your solr server is now available by visiting
http://localhost:8983/solr/admin/

For those using PHP 5.1, you must either install the PECL json extension
into PHP on your sever, or you may use the Zend framework Json library.
for the PECL extension see:  http://pecl.php.net/package/json
The Solr client has been tested with Zend framework release 1.7.7.
To get this code, you may use svn from the apachesolr directory:
svn co http://framework.zend.com/svn/framework/standard/tags/release-1.7.7/library/Zend
However, the only required parts are:
http://framework.zend.com/svn/framework/standard/tags/release-1.7.7/library/Zend/Exception.php
http://framework.zend.com/svn/framework/standard/tags/release-1.7.7/library/Zend/Json/
The 'Zend' directory should normally be under the apachesolr
directory, but may be elsewhere if you set that location to be
in your PHP include path.

Now, you should  enable the "Apache Solr framework" and "Apache Solr search" 
modules. Check that you can connect to Solr at ?q=admin/setting/apachesolr
Now run cron on your Drupal site until your content is indexed. You
can monitor the index at ?q=admin/settings/apachesolr/index

The solrconfig.xml that comes with this modules defines auto-commit, so
it may take a few minutes between running cron and when the new content
is visible in search.

Enable blocks for facets first at Administer > Site configuration > Apache Solr > Enabled filters,
then position them as you like at Administer > Site building > Blocks.   

Troubleshooting
--------------
Problem:
Links to nodes appear in the search results with a different host name or
subdomain than is preferred.  e.g. sometimes at http://example.com
and sometimes at http://www.example.com

Solution:
Set $base_url in settings.php to insure that an identical absolute url is
generated at all times when nodes are indexed.  Alternately, set up a re-direct
in .htaccess to prevent site visitors from accessing the site via more than one
site address.


Developers
--------------

Exposed Hooks in 6.x:

hook_apachesolr_modify_query(&$query, &$params, $caller);

  Any module performing a search should call apachesolr_modify_query($query, $params, 'modulename'). 
  That function then invokes this hook. It allows modules to modify the query object and params array. 
  $caller indicates which module is invoking the hook.

  Example:

        function my_module_apachesolr_modify_query(&$query, &$params, $caller) {
          // I only want to see articles by the admin!
          $query->add_field("uid", 1);         
        }        
    
hook_apachesolr_cck_field_mappings

hook_apachesolr_node_exclude($node)

  This is invoked by apachesolr.module for each node to be added to the index - if any module
  returns TRUE, the node is skipped for indexing. For example, this is used by apachesolr_search
  module to exclude certain node types from the index.

hook_apachesolr_update_index(&$document, $node)

  Allows a module to change the contents of the $document object before it is sent to the Solr Server.

hook_apachesolr_search_result_alter(&$doc)

  The is invoked by apachesolr_search.module for each document returned in a search - new in 6.x-beta7
  as a replacement for the call to hook_nodeapi().

hook_apachesolr_sort_links_alter(&$sort_links)

  Called by the sort link block code. Allows other modules to modify, add or remove sorts.