README.md in bento_search-0.9.0 vs README.md in bento_search-1.0.0
- old
+ new
@@ -1,13 +1,9 @@
# BentoSearch
[](http://travis-ci.org/jrochkind/bento_search)
-(Fairly robust and stable at this point, but still pre-1.0 release, may
-be some breaking api changes before 1.0, but probably not too many, it's
-looking pretty good).
-
bento_search provides an abstraction/normalization layer for querying and
displaying results from external search engines, in Ruby on Rails. Requires
Rails3 and tested only under ruby 1.9.3.
### Goals: To help you
@@ -86,18 +82,18 @@
~~~~ruby
engine = BentoSearch::GoogleBooksEngine.new(:api_key => "my_gbs_api_key")
results = engine.search("a query")
~~~~
-`results` are a BentoSearch::Results object, which acts like an array of
-BentoSearch::Item objects, along with some meta-information about the
+`results` are a [BentoSearch::Results](./app/models/bento_search/results.rb) object, which acts like an array of
+[BentoSearch::Item](./app/models/bento_search/results.rb) objects, along with some meta-information about the
search itself (pagination keys, etc). BentoSearch::Results and Item fields
are standardized accross engines. BentoSearch::Items provide semantic
values (title, author, etc.), as available from the particular engine.
To see which engines come bundled with BentoSearch, and any special
-engine-specific instructions, look at BentoSearch source in `./app/search_engines`
+engine-specific instructions, look at BentoSearch source in [`./app/search_engines/bento_search`](./app/search_engines/bento_search)
### Register engines in global configuration
It can be convenient to register an engine in global configuration, and is
required for certain functionality (like out-of-the-box AJAX loading).
@@ -209,11 +205,11 @@
~~~~
bento_search fixes the default per_page at 10.
For help creating your UI, you can ask a BentoSearch::Results for
-`results.pagination`, which returns a BentoSearch::Results::Pagination
+`results.pagination`, which returns a [BentoSearch::Results::Pagination](app/models/bento_search/results/pagination.rb)
object which should be suitable for passing to [kaminari](https://github.com/amatsuda/kaminari)
`paginate`, or else have convenient methods for roll your own pagination UI.
Kaminari's paginate method:
~~~~ruby
@@ -257,11 +253,11 @@
BentoSearch doesn't automatically include the celluloid dependency. Note
that Celluloid uses multi-threading in such a way that you might need
to turn Rails config.cache_classes=true even in development.
-For more info, see BentoSearch::MultiSearcher.
+For more info, see [BentoSearch::MultiSearcher](./app/models/bento_search/multi_searcher.rb).
### Delayed results loading via AJAX (actually more like AJAHtml)
BentoSearch provides some basic support for initially displaying a placeholder
progress spinner, and having Javascript call back to get the actual results.
@@ -287,11 +283,12 @@
link resolver.
BentoSearch::Items can have a main link associated with them (generally
hyperlinked from title), as well as a list of additional links. Most engines
do not provide additional links by default, custom local Decorators would
-be used to add them. See wiki for more info on decorators, and BentoSearch::Link
+be used to add them. See [wiki on display cusotmization](https://github.com/jrochkind/bento_search/wiki/Customizing-Results-Display)
+for more info on decorators, and [BentoSearch::Link](app/models/bento_search/link.rb)
for fields.
### OpenURL and metadata
Academic library uses often need openurl links from scholarly citations. One of
@@ -305,12 +302,12 @@
especially the format/type of results (See bento_search's internal format/type vocabulary
documented at ResultItem#format). As well as how well the #to_openurl routine
handles all edge cases (OpenURL can be weird). As edge cases are discovered, they
can be solved.
-See `./app/item_decorators/bento_search/openurl_add_other_link.rb` for an example
-of using item decorators to add a link to your openurl resover to an item when
+See [`./app/item_decorators/bento_search/openurl_add_other_link.rb`](./app/item_decorators/bento_search/openurl_add_other_link.rb)
+for an example of using item decorators to add a link to your openurl resover to an item when
displayed.
### Exporting (eg as RIS) and get by unique_id
A class is included to convert an individual BentoSearch::ResultItem to
@@ -320,13 +317,39 @@
ris_data = RISCreator.new( bento_item ).export
~~~
Accomodating actual exports into the transactional flow of a web app can be
tricky, and often requires use of the `result_item#unique_id` and
-`engine.get( unique_id )` features. See the wiki at
+`engine.get( unique_id )` features. See the wiki on [exports and #unique_id](https://github.com/jrochkind/bento_search/wiki/Exports-and-the-get-by-unique_id-feature)
+### Machine-readable serialization in Atom
+Translation of any BentoSearch::Results to an Atom response that is enhanced to
+include nearly all the elements of each BentoSearch::ResultItem, so can serves
+well as machine-readable api response in general, not just for Atom feed readers.
+
+You can use the [`bento_search/atom_results`](./app/views/bento_search/atom_results.atom.builder) view template, perhaps
+in your action method like so:
+
+~~~ruby
+# ...
+respond_to do |format|
+ format.html # default view
+ format.atom do
+ render( :template => "bento_search/atom_results",
+ :locals => {
+ :atom_results => @results,
+ :feed_name => "Acme results",
+ :feed_author_name => "MyCorp"
+ }
+ )
+end
+~~~
+
+There are additional details that might matter to you, for more info see the
+[wiki page](https://github.com/jrochkind/bento_search/wiki/Machine-Readable-Serialization-With-Atom)
+
## Planned Features
I am trying to keep BentoSearch as simple as it can be to conveniently meet
actual use cases. Trying to avoid premature over-engineering, and pave
the cowpaths as needed.
@@ -338,10 +361,20 @@
also may be supported by some engines that do not support facetting).
* Support for multi-field, multi-entry-box 'advanced search' UI's, in
a normalized cross-engine way.
Other needs or suggestions?
-
+
+## Backwards compat
+
+We are going to try to be strictly backwards compatible with all post 1.0
+releases that do not increment the major version number (semantic versioning).
+
+As a general rule, we're going to let our tests enforce this -- if a test has
+to be changed to pass with new code, that's a very strong sign that it is
+not a backwards-compat change, and you should think _very_ carefully to
+be sure it is an exception to this rule before changing any existing tests
+for new functionality.
## Developing
BentoSearch is fairly well covered by automated tests. We simply use Test::Unit.
Run tests with `rake test`.