Skip to content

Commit

Permalink
Archive 5.9 documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@cbeer
cbeer committed Feb 21, 2015
1 parent 40ee01b commit 751c0f2
Show file tree
Hide file tree
Showing 34 changed files with 3,211 additions and 0 deletions.
94 changes: 94 additions & 0 deletions doc/Adding-new-document-actions.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
In your `CatalogController`, you can register document actions that display in various places within the default Blacklight UI:

- `add_show_tools_partial`: displays on the `catalog#show` page, using the `render_show_doc_actions` helper
- `add_results_document_tool`: displays on every search result, using the `render_index_doc_actions` helper
- `add_results_collection_tool`: displays at the top of a search result page, using the `render_results_collection_tools` helper
- `add_nav_action`: displays in the top application navbar, using the `render_nav_actions` helper

All types of actions take the same parameters, e.g.:

```ruby
##
# Add a partial to the tools for rendering a document
# @param partial [String] the name of the document partial
# @param opts [Hash]
# @option opts [String] :partial render this action using the provided partial
# @option opts [Symbol,Proc] :if render this action if the method identified by the symbol or the proc evaluates to true.
# The proc will receive the action configuration and the document or documents for the action.
# @option opts [Symbol,Proc] :unless render this action unless the method identified by the symbol or the proc evaluates to true
# The proc will receive the action configuration and the document or documents for the action.
def add_show_tools_partial name, opts = {}
```

Examples:

```
class CatalogController
...
# only show patron information if a user is logged in. Note that `current_user?` has to be defined as a helper method
add_nav_action :patron_information, if: :current_user?
# In Rails 4+, this can also be defined using an inline proc:
add_nav_action :patron_information, if: Proc.new { |context, config, options| context.current_user? }
# Actions can also trigger based on properties of the document:
add_show_tools_partial :download_image_widget, if: Proc.new { |context, config, options| options[:document].image? }
...
end
```


## Show Tools
You can register an action that displays on the document show page using the `add_show_tools_partial` controller method. In addition to the functionality offered by the other types of tools and actions, show tools also offer conventional defaults.

Here is a trivial example of registering a new type of action:

```ruby
# app/controllers/catalog_controller.rb
class CatalogController
add_show_tools_partial :my_custom_action

## OPTIONAL
# def my_custom_action
# # render some content..
# # by default, Blacklight will try to render the partial of the same name (i.e. `app/views/catalog/my_custom_action.html.erb`)
# end
end

# config/routes
Rails.application.routes.draw do
...
get '/catalog/:id/my_custom_action' => 'catalog#my_custom_action', as: 'my_custom_action_catalog'
end
```


If the action will receive form data from a `POST` request, you can also register a callback for handling that request. Optionally, the `POST` params can be validated using a helper method.

```ruby
class CatalogController
include Blacklight::Catalog
...

# Register a new action called "email".
# On a POST request, validate the params using the `#validate_email_params` method
# and process the request using `#email_action`.
add_show_tools_partial :email, callback: :email_action, validator: :validate_email_params

def validate_email_params
# validate that the posted params are suitable for the action
end

def email_action documents
# send an email with the attached documents
end

...
end
```

By convention, the action name is used to determine the route name for the action. For this email action, Blacklight will link to `email_catalog_path`.

The action will render the template [`catalog/email.html.erb`](https://github.com/projectblacklight/blacklight/blob/master/app/views/catalog/email.html.erb) template when the action is selected. This template provides a form, which, when submitted, will trigger the `email_action` method and will render the [`catalog/email_success.html.erb`](https://github.com/projectblacklight/blacklight/blob/master/app/views/catalog/email_success.html.erb) template.
90 changes: 90 additions & 0 deletions doc/Atom-Responses.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
Blacklight will provide atom responses for all catalog/index results. Just add ".atom" on to the end of your path component, `/catalog.atom`, or `/catalog/index.atom`.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns="http://www.w3.org/2005/Atom">
<title>Blacklight Search Results</title>
<author>
<name>Blacklight</name>
</author>
<link href="http://demo.projectblacklight.org/?commit=search&amp;amp;format=atom&amp;amp;q=urdu&amp;amp;search_field=all_fields" rel="self"/>
<link href="http://demo.projectblacklight.org/?commit=search&amp;amp;format=html&amp;amp;q=urdu&amp;amp;search_field=all_fields" rel="alternate" type="text/html"/>
<id>http://demo.projectblacklight.org/?commit=search&amp;amp;format=html&amp;amp;q=urdu&amp;amp;search_field=all_fields&amp;amp;type=text%2Fhtml</id>
<link href="http://demo.projectblacklight.org/?commit=search&amp;amp;format=atom&amp;amp;page=2&amp;amp;q=urdu&amp;amp;search_field=all_fields" rel="next"/>
<link href="http://demo.projectblacklight.org/?commit=search&amp;amp;format=atom&amp;amp;page=1&amp;amp;q=urdu&amp;amp;search_field=all_fields" rel="first"/>
<link href="http://demo.projectblacklight.org/?commit=search&amp;amp;format=atom&amp;amp;page=15&amp;amp;q=urdu&amp;amp;search_field=all_fields" rel="last"/>
<link href="http://demo.projectblacklight.org/catalog/opensearch.xml" rel="search" type="application/opensearchdescription+xml"/>
<opensearch:totalResults>147</opensearch:totalResults>
<opensearch:startIndex>0</opensearch:startIndex>
<opensearch:itemsPerPage>10</opensearch:itemsPerPage>
<opensearch:Query searchTerms="urdu" startPage="1" role="request"/>
<updated>2011-05-11T17:46:58Z</updated>
<entry>
<title>Urdu&#772; d&#803;ra&#772;ma&#772;</title>
<updated>2011-05-11T17:46:58Z</updated>
<link href="http://demo.projectblacklight.org/catalog/2008306442" rel="alternate" type="text/html"/>
<link href="http://demo.projectblacklight.org/catalog/2008306442.dc_xml" rel="alternate" title="dc_xml" type="text/xml" />
<link href="http://demo.projectblacklight.org/catalog/2008306442.xml" rel="alternate" title="xml" type="application/xml" />
<id>http://demo.projectblacklight.org/catalog/2008306442</id>
<author>
<name>Farg&#818;h&#818;a&#772;nah, 1979-</name>
</author>
<summary type="html">
&lt;dl class="defList"&gt;


&lt;dt class="blacklight-title_display"&gt;Title:&lt;/dt&gt;
&lt;dd class="blacklight-title_display"&gt;Urdu&#772; d&#803;ra&#772;ma&#772;&lt;/dd&gt;

&lt;dt class="blacklight-author_display"&gt;Author:&lt;/dt&gt;
&lt;dd class="blacklight-author_display"&gt;Farg&#818;h&#818;a&#772;nah, 1979-&lt;/dd&gt;


<!-- [...] -->
&lt;/dl&gt;
</summary>
</entry>
<!-- [...] -->
</feed>
```


The same HTML summary included in your HTML results pages are included as an `atom:summary` element -- the atom template uses the `[[#render_document_partial|https://github.com/projectblacklight/blacklight/blob/master/app/helpers/blacklight/blacklight_helper_behavior.rb#L203]]` helper method to generate this HTML summary, so if you've over-ridden that for your app, it will be used as the `atom:summary` content instead.

## API Usage
The Atom response is intended to be pretty full of data, so it can fill many traditional API requests. It makes use of every relevant atom or [[OpenSearch|http://www.opensearch.org/Home]] element that could be conveniently included.

The Atom response also supports arbitrary format representations in the `atom:content` element. You can include `&content_format=some_format` in your request URL (e.g. `[[/catalog.atom?content_format=oai_dc_xml|http://demo.projectblacklight.org/catalog.atom?q=urdu&content_format=oai_dc_xml]]`). Any format a given document can be exported as using the [[Blacklight document framework|Extending-blacklight-with-the-document-extension-framework]] is available. Not every document can export in every format -- if a format is requested one or more of the items in your atom result can not export as, it will not have an `atom:content` element. Non-XML-based formats are supported, as the content is Base64-encoded (as per Atom spec, unless the format is `text/plain`).
```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns="http://www.w3.org/2005/Atom">
<title>Blacklight Search Results</title>
<author>
<name>Blacklight</name>
</author>
<link href="http://demo.projectblacklight.org/?content_format=oai_dc_xml&amp;amp;format=atom&amp;amp;per_page=1" rel="self"/>
<!-- [...] -->
<entry>
<title>The book of the dance in the 20th century selections from the Jane Bourne Parton collection of books on the dance</title>
<updated>2011-05-11T17:59:32Z</updated>
<link href="http://demo.projectblacklight.org/catalog/u1" rel="alternate" type="text/html"/>
<link href="http://demo.projectblacklight.org/catalog/u1.dc_xml" rel="alternate" title="dc_xml" type="text/xml" />
<link href="http://demo.projectblacklight.org/catalog/u1.xml" rel="alternate" title="xml" type="application/xml" />
<id>http://demo.projectblacklight.org/catalog/u1</id>
<author>
<name>Roatcap, Adela Spindler</name>
</author>
<summary type="html">
<!-- [...] -->
</summary>
<!-- [ Here is the export format as OAI Dublin Core XML ] -->
<content type="text/xml">
<oai_dc:dc xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><dc:language>English</dc:language><dc:title>The book of the dance in the 20th century selections from the Jane Bourne Parton collection of books on the dance</dc:title><dc:format>Book</dc:format></oai_dc:dc> </content>
</entry>
</feed>
```

This means that if you add on a document extension that provides more export formats for some or all of your documents, that will automatically be available in the atom response.

If you choose to use the [[Blacklight CQL add-on|https://github.com/projectblacklight/blacklight_cql]], the combination of [[CQL|http://www.loc.gov/standards/sru/specs/cql.html]] requests and Atom responses provides a pretty good more-or-less standards-based API to search results through Blacklight.

The Atom response generating template is at `app/views/catalog/index.builder.atom`.
23 changes: 23 additions & 0 deletions doc/Blacklight-Add-ons.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
## Stable Add-ons

A few add-ons are are more or less 'officially supported', and all Blacklight developers have commit rights on them. (although some may not have received attention in a while if developers have been busy. Feel free to ask on the list for current status):

* [Advanced search](https://github.com/projectblacklight/blacklight_advanced_search)
* [CQL search](https://github.com/projectblacklight/blacklight_cql)
* [Date range limit](https://github.com/projectblacklight/blacklight_range_limit).

## In development
* [Blacklight Gallery](https://github.com/projectblacklight/blacklight-gallery)
* [Blacklight Maps](https://github.com/sul-dlss/blacklight-maps)
* [Spotlight](https://github.com/sul-dlss/spotlight) Curated digital collections
* [blacklight-oembed](https://github.com/sul-dlss/blacklight-oembed) Embedding oEmbed resources in search results
* [GeoBlacklight](https://github.com/geoblacklight/geoblacklight) Discovery and access for geospatial data

## Unstable/Experimental

* [[Blacklight Sitemap Generator|https://github.com/jronallo/blacklight-sitemap]]: Rake task for generating sitemaps.
* [[Blacklight OAI provider|https://github.com/cbeer/blacklight_oai_provider]]: Adds an [[OAI-PMH|http://www.openarchives.org/pmh/]] provider using the [[oai|http://rubygems.org/gems/oai]] gem for harvesting records within Blacklight.
* [[Blacklight unAPI|https://github.com/cbeer/blacklight_unapi]]: Adds an [[unAPI|http://unapi.info]] endpoint for records within Blacklight.
* [[Blacklight User Generated Content|https://github.com/cbeer/blacklight_user_generated_content]]: Adds user generated content to SolrDocument objects using acts_as_commentable, acts_as_taggable and acts_as_rateable directly against a SolrDocument object.
* [[Blacklight oEmbed|https://github.com/cbeer/blacklight_oembed]]: [[oEmbed|http://oembed.com]] endpoint that provides framework for allowing third-party sites (Wordpress, Facebook, etc) to embed content given a URL.
* [[Blacklight Google Analytics|https://github.com/jronallo/blacklight_google_analytics]]: Quick start for setting up Google Analytics for a Blacklight site, including Event Tracking of Blacklight-specific page elements like facets.
Loading

0 comments on commit 751c0f2

Please sign in to comment.