OpenSearch JavaScript client
The full documentation is available here.
Setup
To install the client framework perform the following steps:
npm install opensearch-browser
Usage
The easiest way to use the library is by using the discover
function, which
takes a single parameter, the URL of the OpenSearch service:
import { discover } from 'opensearch-browser';
discover('http://example.com/search').then((service) => {
service.search({ searchTerms: 'Test', startIndex: 1 }).then((results) => {
});
});
If you already have the OpenSearch description document locally, you can also
use the fromXml
function to create the service class:
import { fromXml } from 'opensearch-browser';
const osddDocumentString = `
<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
...
</OpenSearchDescription>`;
const service = fromXml(osddDocumentString);
This OpenSearch library requires Promises
. If you are not sure whether you
have it available use the following polyfill:
require('es6-promise').polyfill();
Configuration
This library uses a global configuration interface, provided by the config
function, which is used for getting and setting configuration values:
import { config } from 'opensearch-browser';
const { useXHR, Promise } = config();
config({
useXHR: true,
Promise: Promise,
});
Currently supported are the following config values:
useXHR
: Whether to use the
XMLHttpRequest
or the fetch
API. The former has the advantage that the requests can be
aborted. This is exposed when a Promise
type is used that supports
cancelling, like the great
bluebird library.Promise
: If set, overrides default ES6 Promise with a custom implementation, for example bluebird
.
However bluebird is not set as a dependency to avoid bloating the library.
Request parameters
Request parameters are supplied as an object whose attribute names shall either
be the URL parameter names or their types. For example, if the OpenSearch
service provides a URL like the following example:
<Url type="text/html"
template="http://example.com/search?q={searchTerms}&pw={startPage?}"
/>
then the following request parameters are possible:
service.search({ searchTerms: 'Test', startPage: 1 }).then( ... );
service.search({ q: 'Test', pw: 1 }).then( ... );
service.search({ searchTerms: 'Test' }).then( ... );
An exception will be raised when mandatory parameters are not supplied.
Some parameter types will be automatically translated from their object
to their string representation:
Parameter type | Object | Value |
---|
time:start and time:end | Date | an ISO 8601 string representation |
geo:box | [left, bottom, right, top] | a string "left,bottom,right,top" |
geo:geometry | GeoJSON Geometry Object | the WKT representation |
all numeric types + datetime from eo | Number | "<value>" |
| [value1, value2, ...] | "{<value1>,<value2>,...}" |
| { min: minValue, max: maxValue } | "[<minValue>,<maxValue>]" |
| { min: minValue } | "[<minValue>" |
| { max: maxValue } | "<maxValue>]" |
| { minExclusive: minValue } | "]<minValue>" |
| { maxExclusive: maxValue } | "<maxValue>[" |
| ... | |
Search Results
By default, the library is able to parse RSS, Atom and GeoJSON responses. They
are parsed to a structure based upon the GeoJSON format.
It is possible to extend the supported formats by adding additional format
handlers:
import { registerFormat } from 'opensearch-browser';
const format = {
parse: function(text) {
return ...;
}
};
registerFormat('application/vnd.special+xml', format);
When a search URL is used with that mime-type, the response is now parsed with
the registered handler.
Alternatively, raw responses can be used, and parsing be performed outside of
this library:
const mimeType = null;
const raw = true;
service.search({ searchTerms: 'Test', startIndex: 1 }, mimeType, raw)
.then(function(response) {
});
For both cases, the response is a
Response object
from the fetch
API.
Suggestions
This library also supports the Suggestions extension of OpenSearch. This is
implemented on the Service
via the getSuggestions
method:
service.getSuggestions({ searchTerms: 'someth' })
.then(function(suggestions) {
for (let i = 0; i < suggestions.length; ++i) {
console.log(
suggestion.completion,
suggestion.description,
suggestion.url
);
}
});
For this to work, the server must have a search url with the type
application/x-suggestions+json
defined.
Testing
To run the unit tests do
npm test
To run the unit tests continuously, run the following command:
npm run test:watch
Documentation
To generate the API documentation run:
npm run docs
Notes
This library aims to provide a broad support of the most common OpenSearch
functionality and exchange formats. It also supports the
Geo,
Time,
EO Products,
Parameters, and
Suggestions
extensions and adheres to various points of the
CEOS OpenSearch best practice paper.