Adding new document actions

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.:

      ##
      # 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?

  # 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:

# 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.

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 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 template.

Removing actions

Note that it is also possible to delete document actions as follows:

# app/controllers/catalog_controller.rb
config.show.document_actions.delete(:citation)