When you are overridding default controllers or adding new sections and search presets, you may find yourself needing to create custom API requests.
When you first start an Orchid app, it connects to the API endpoint specified
in your config/private.yml file with default settings from config/public.yml.
That Query object is stored with a global variable:
$apiTypically, you will not need to work directly with $api. In the
ItemsController, you are provided with an instance variable:
@items_api@items_api will return either $api or a section appropriate connection, if
you are working with sections.
The section API connection information is stored in $api_sections, although
you should rarely need to use it directly.
Orchid uses the CDRH API's syntax for requests. You should familiarize yourself with the API documentation before writing custom requests.
When you initialize your application, Orchid sets up default query parameters using your config file settings.
This means that you do not need to specify things such as the number of items per page, starting sort, facets, and any default filters for new queries, since they are already built in as a convenience.
However, you may override those defaults as desired when creating a new query.
A typical query will look something like this:
@items_api.query({ hash of options })For example, the following would bring back results of Willa Cather's writing with the text "birthday":
options = {
"f" => [ "category|Writings", "creator.name|Cather, Willa" ],
"q" => "birthday"
}
@items_api.query(options).query returns a Response object which has the following methods:
- count : the number of items found
- facets : a hash with facets + facet counts you requested
- items : an array of the documents you requested
- first : the first item
- pages: the page count needed to display all the items
Although you could send a .query({ identifier: "some.id" }) request and
select the first item, orchid provides a helpful method to get a single item:
@items_api.get_item_by_id("some.id").first