Skip to content

Latest commit

 

History

History
66 lines (39 loc) · 3.5 KB

customizing_searchers.md

File metadata and controls

66 lines (39 loc) · 3.5 KB
Raw

Customizing Searchers

Creating a Searcher

Writing the Code

A searcher in QuickSearch is a Rails Gem Engine. To create an empty Gem Engine, you can run the command:

rails plugin new <my_searcher_name> --mountable

This creates a new directory called [my_searcher_name], with a skeleton gem engine. There are several important files to create/edit when creating a searcher:

[my_searcher_name].gemspec

This file is automatically generated by Rails, and contains information about this gem. You just need to fill it in with the appropriate information pertaining to your searcher. Also, you define dependencies to your gem in here.

Gemfile

This is another place where you should define any of the dependencies to your gem, or development dependencies.

app/searchers/quick_search/[my_searcher_name]_searcher.rb

This is where you would write actual searcher code. This file should contain a class called “[MySearcherName]Searcher” that subclasses QuickSearch::Searcher. This class should be inside the QuickSearch module.

A searcher is only required to have two methods implemented (if these are not implemented, you will get errors):

  • search() which performs the actual search
  • results() which returns the results from your search

You can define as many other methods as you need in your [MySearcherName]Searcher class.

config/[my_searcher_name]_config.yml

This is where you would include any configurable options that your searcher uses. For non-sensitive configuration options, set sensible defaults. Otherwise, leave the values blank (or use fake values). For any configuration that someone would normally need to set when using the module, leave instructions in the form of comments.

The configuration is converted from YAML into a Ruby Hash object when QuickSearch is initialized. You can refer to this configuration in your searcher code by using the following Hash constant under the 'QuickSearch::Engine' namespace: QuickSearch::Engine::[MY_SEARCHER_NAME]_CONFIG

so if your searcher was called Catalog, and you were trying to get the value from the configuration option 'catalog_api_url', it would be:

QuickSearch::Engine::CATALOG_CONFIG['catalog_api_url']

config/locales/en.yml (or any other locale depending on the language you use)

Specify any strings that your searcher template uses in here. QuickSearch usually expects that searchers have at least the following strings available:

  • display_name: "Display Name of the searcher, used as the heading for the searcher display"
  • short_display_name: "A shorter version of the display name"
  • search_form_placeholder: "Something like: ‘Search our catalog!’"
  • module_callout: "Displayed when there i"

config/initializers/[my_searcher_name]_searcher_config.rb

If you include a config file with your searcher, you need to create this file to enable the config to be loaded when the QuickSearch application starts. Here's the recommended content for this file:

#Try to load a local version of the config file if it exists - expected to be in quicksearch_root/config/searchers/<my_searcher_name>_config.yml

if File.exists?(File.join(Rails.root, "/config/searchers/<my_searcher_name>_config.yml"))
  config_file = File.join Rails.root, "/config/searchers/<my_searcher_name>_config.yml"
else
  # otherwise load the default config file
  config_file = File.expand_path("../../<my_searcher_name>_config.yml", __FILE__)
end
QuickSearch::Engine::<MY_SEARCHER_NAME_CAPS>_CONFIG = YAML.load_file(config_file)[Rails.env]