root/django/trunk/utils/googlesearch/docs.txt

Django Google Search
--------------------

Django Google Search is a simple wrapper around Google Site
Search. You can use it to add a custom, Google-powered search engine
to your Web site by using Google Site Search XML service.

Even though this application is free, a key for Google Site Search is
needed to make it work.

http://www.google.com/sitesearch/


REQUIREMENTS
------------

Django Google Search requires at least Django 0.96 running on Python
2.3+. 

The ElementTree library for XML parsing is also required for Python
2.3 and 2.4, whereas Python 2.5+ have ElementTree built-in and Django
Google Search knows how to find it.


INSTALL
-------

Put the googlesearch directory anywhere in your PYTHONPATH and add
"googlesearch" to your Django INSTALLED_APPS.

You’ll need to add a key to your per-project settings file with this
entry:

  G_BUSINESS_KEY = '<your Google business key here>'

You’ll also need to wire the app in your global urls.py:

  (r'^search/$', 'googlesearch.views.search'),

Assuming you have a base.html master template this is all you need to
do for now. If not, create one with a basic HTML page skeleton, a
block called “title”, and another called “content” in the spots you
find best and Django Google Search will pick it up.


CONFIGURATION
-------------

There are other parameters you can configure:

- G_LANGUAGE_CODE, which specifies how Google replies to your queries

- G_NUM_RESULTS, how many results you want on each page


TEMPLATES
---------

- goooglesearch/search.html

As stated above, by default Django Google Search has a few custom
templates. The main one is googlesearch/search.html, the other two
extend this.

You may override googlesearch/search.html with your own, just remember
to create a block called “results” for the other two templates to
write into.

- googlesearch/no_results.html

Default template for “no results” scenario.

- googlesearch/not_available.html

Default template displayed when the Google XML service is down.


VIEWS
-----

- googlesearch.views.search

Django Google Search has a single view, “search”, that receives the
GET parameter “q”, calls Google XML service, parses the XML response
and finally renders it via the googlesearch/search.html template.

This view also accepts the “page” parameter, for pagination. It
doesn’t use the default Django pagination system because Google’s
pagination results are unpredictable.

The “search” view instantiates a RequestContext by default, so you
have access to all the request objects from the template, including
“request.user”. 

It takes three parameters, all optional:

- G_BUSINESS_KEY (str), defaults to the business key specified in the
  settings, but can be overridden in case you want to work with
  multiple keys for any reason.

- extra_context (dict), stuff you may want to pass as extra variables
  in the template context

- extra_query_params (dict), extra query parameters you may want to
  pass to Google, like a custom site:http://example.org/ filter to
  provide sub-site search support


ACKNOWLEDGEMENTS
----------------

For all the bugs in the current version of Django Google Search blame
its original writer, Antonio Cavedoni <http://cavedoni.com/>

Other people that have helped with suggestions and fixes:

- Marco Beri <http://beri.it/>
- Your Name Here


$Id$