What is acts_as_zoom?
======================
This plugin adds full text search capabilities using ruby-zoom to connect a Z39.50 server to any Rails model.

Note, it was written for the Kete project (http://kete.net.nz)
and may not work for your project.

It was based on the acts_as_solr plugin.

TODO: make this accurate
Current Release: 0.01
====================
Not yet released

Changes I made:
===============
Please refer to the change log

Requirements:
======
This plugin requires that you have at least one zoom compatible (i.e. a Z39.50 standard based server like Zebra) server to connect to.  It installs a model called ZoomDb for keeping track of your Z39.50 server settings.  You will need a migration for installing the table supporting the model and may also want to add a controller for it.  Here's the code for the migration:

class CreateZoomDbs < ActiveRecord::Migration
  def self.up
    create_table :zoom_dbs do |t|
      t.column :database_name, :string, :null => false
      t.column :description, :text
      t.column :host, :string, :null => false
      t.column :port, :text, :null => false
      t.column :zoom_user, :string
      t.column :zoom_password, :string
      t.column :created_at, :datetime, :null => false
      t.column :updated_at, :datetime, :null => false
    end
  end

  def self.down
    drop_table :zoom_dbs
  end
end

This plugin uses the ruby-zoom library (http://ruby-zoom.rubyforge.org/) to implement the ZOOM API.  You can find instructions on how to install ruby-zoom, along with Zebra and YAZ, on Debian testing/etch here:

http://blog.katipo.co.nz/?p=26

Usage:
======
You will need to define at least one Z39.50 server to point acts_as_zoom via ZoomDb class instance.  After that you have several options to specify.

You need to choose some combinattion of save_to_public_zoom (anonymous read allowed) or save_to_private_zoom (limited to user with password) Z39.50 databaes.  If you use a private zoom, the save_zoom method will check your object to see if it has a private attribute set to true or false.  In other words, you need to include it your model for this option to work.

  acts_as_zoom :fields => [:title, :description], :save_to_public_zoom => ['zoom_database_host', 'zoom_database_name'], :save_to_private_zoom => ['zoom_database_host', 'zoom_database_name']

Note: errors where you have a nil object and the message has "nil.host" are most likely related to a mismatch in your zoom_dbs, either you have specified in your acts_as_zoom options wrong, the zoom_db hasn't been entered as a ZoomDb instance or it's attributes are incorrect.

The last option is whether to put the fields specified in XML or not (defaults XML formatting on):

  ..., :raw => true }

If you choose raw, it assumes that only a single field is specified.  This assumption is based around the idea that that single field is actually a virtual attribute that has the pre-formatted record stuffed in it.

If you have existing data for you model, you'll probably want to run rebuild_zoom_index for the class.

You may also want to mess with how zoom_id is formated and placed in the record.  It is highly dependent on how the Z39.50 you are accessing is configured.

!!!YOU WILL need to add some variation of the following to the end of your app/conf/environment.rb file

# used by the acts_as_zoom plugin
ZoomDb.zoom_id_stub = ""
ZoomDb.zoom_id_element_name = "localControlNumber"
# in case your zoom_id is in a nested element
# separated by /'s
# no preceding / necessary
ZoomDb.zoom_id_xml_path_to_element = "record/header"

How you formulate your queries and generally use your connections is beyond the scope of this document.  However, we recommend you take a look at the Kete application for examples (rather complex, but should be useful).  You can find out more here:

http://kete.net.nz/

Authors:
========

Walter McGinnis walter@katipo.co.nz

Based on work by acts_as_solr authors:

Erik Hatcher  => First draft
Thiago Jackiw => tjackiw@gmail.com

Special Thanks to:
==================
Horowhenua Library Trust (http://www.library.org.nz/)

The Zebra team at Index Data (http://indexdata.dk/zebra/)

acts_as_solr plugin team

the Ruby ZOOM project

Nicolai Moles-Benfell for adding ZOOM Extended Services to the Ruby ZOOM project!

Released under the GPL License.