Adding a local authority module

Overview

For complex custom controlled vocabularies that require extra processing to be able to process search or fetch requests, a local module similar to those created for inclusion in QA can be created. It is recommended that you look at Contributing a new external authority for details on creating a module. The only difference is that your module will be defined in your local app as opposed to being added to the QA code base. If your module is of general interest to the community, you are encouraged to submit a PR to contribute your module to core QA.

Prerequisites

Write the module

Write a class (e.g. 'LocalNames') that implements the #search, #find, and #all methods that will be called from TermsController. See Contributing a new external authority for more information on the typical implementation of these methods.

This is a basic pattern you can follow for the module class.

# app/authorities/qa/authorities/local_names.rb
module Qa::Authorities
  class LocalNames < Qa::Authorities::Base
    # Arguments can be (query) or (query, terms_controller)
    def search(_q)
      # Should return array of hashes with ids, labels, and values(optional)
      [{"id":"id_1",  "label":"Anna Zoia",    value":"Anna Zoia value"},
       {"id":"id_3",  "label":"Charles Zoia", "value":"Charles Zoia value"}]
    end
    
    # Arguments is (id) or (uri)
    def term(_id)
      # Should return hash with id, label, and value(optional) for a single term for the specified id
      { id: 'id_25', label: 'Zoia Ch', value: 'Zoia Ch value' }
    end
    
    # No arguments
    def all
      # Should return an array of hashes with ids, labels, and values (optional) for all (or first 1000 if large vocabulary) terms
      [{"id":"id_1",  "label":"Anna Zoia",    value":"Anna Zoia value"},
       {"id":"id_2",  "label":"Brady Jones", "value":"Brady Jones value"},
       {"id":"id_3",  "label":"Charles Zoia", "value":"Charles Zoia value"},
       ...
       {"id":"id_25", "label":"Zoia Ch", "value":"Zoia Ch value"}]
    end
  end
end

NOTES:

• Substitute in place of local_names.rb and class LocalNames the names of the class your create for the authority.

Register your authority in an initializer

Registration of module based controlled vocabularies needs to happen everytime the server restarts. The following registers the names authority. You can put the statement in any initializer. One option is to put it in config/initializers/qa.rb.

Qa::Authorities::Local.register_subauthority('names', 'LocalNames')

NOTES:

• Substitute in place of 'names' the namespace you will use to identify this vocabulary in the QA request URLs.
• Substitute in place of 'LocalNames' the name of the class you wrote implementing the authority methods (i.e. #search, #find, #all). You do not have to implement all three methods, but they should return gracefully if not fully implemented.

Accessing via QA

Authority:	local

Subauthorities:

• namespace_used_when_registering_the_local_subauthority (e.g. names)

---

Examples

All examples are shown using the names authority. Substitute in place of names the namespace used when registering the local subauthority.

Example search queries for custom vocabulary names:

/qa/search/local/names?q=Zoia

Result:

The actual results will be driven by the json returned from the #search method in your local module class (e.g. LocalNames). The results should be something like...

[
  {"id":"id_1","label":"Anna Zoia"},
  {"id":"id_3","label":"Charles Zoia"},
  {"id":"id_25","label":"Zoia Ch"}
]

NOTES:

• Search searches terms, but not IDs/URIs. If you search for q=id_, the result set will be empty.
• Search is NOT case-sensitive. The result set is the same when searching for q=zoia.

---

Example term fetch request for custom vocabulary names:

/qa/show/local/languages/id_3

Result:

The actual results will be driven by the json returned from the #find method in your local module class (e.g. LocalNames). The results should be something like...

{"id":"id_3","label":"Charles Zoia"}

---

Example list all terms for custom vocabulary names

If the vocabulary is large, you may want either not implement this request or have it return the first 1000 terms.

/qa/terms/local/names

Result:

The actual results will be driven by the json returned from the #all method in your local module class (e.g. LocalNames). The results should be something like...

[
  {"id":"id_1","label":"Anna Zoia"},
  {"id":"id_2","label":"Betty Jones"},
  {"id":"id_3","label":"Charles Zoia"},
  etc.
]

---

Documentation

This is a locally defined controlled vocabulary and does not have any associated documentation.