OpenSearchlight
OpenSearchlight copied to clipboard
An OpenSearch client in JavaScript
OpenSearchlight
A JavaScript OpenSearch client that configures itself around an OpenSearch Description Document, making queries against OpenSearch services a little easier from JS clients.
Download
Download the minified version or the development version.
Usage
Assuming you're trying to use an OpenSearch service whose OSDD at http://www.example.com/opensearch?description contains the following:
<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Web Search</ShortName>
<Description>Use Example.com to search the Web.</Description>
<Url type="application/atom+xml"
template="http://example.com/?q={searchTerms}&pw={startPage?}&n={resultsPerPage?}&format=atom"/>
<Url type="text/html"
template="http://example.com/?q={searchTerms}&pw={startPage?}&n={resultsPerPage?}"/>
<Query role="example" searchTerms="cat" />
</OpenSearchDescription>
In your web page, the following code will retrieve search results for "steely", in ATOM format, starting at the second page with ten results per page:
<script src="jquery.js"></script>
<script src="OpenSearchlight.min.js"></script>
<script>
OpenSearchlight.query({
osdd: "http://www.example.com/opensearch?description",
contentType: "application/atom+xml",
requestHeaders: [{name: "X-Requested-With", value: "MyApp"}],
parameters: {
searchTerms: "steely",
startPage: "2",
resultsPerPage: "10"
},
success: function (data) {
// data contains results!
},
error: function (jqXHR, textStatus, errorThrown) {
// error handling...
}
});
</script>
Documentation
See the annotated source.
License
OpenSearchlight is licensed under the MIT license. See LICENSE.txt.
Credit
This software was developed by the National Snow and Ice Data Center, sponsored by National Science Foundation grant number OPP-10-16048.
Release History
- 0.4.0
- Added optional requestHeaders parameter to OpenSearchQuery
- 0.3.0
- OSDD fetch will now call error callback on request failure.
- 0.2.3
- Added an optional callback function in OpenSearchQuery API
- 0.2.2
- Upgraded to Grunt 0.4
- 0.2.1
- Added a simpler API
- Fixed a bug handling optional parameters
- 0.1.2
- Fixed bug preventing empty optional parameters from being filled with empty string
- Added Release Checklist to documentation
- 0.1.1
- Documentation fixes
- 0.1.0
- Initial release
OpenSearchlight uses semantic versioning.
Developer Notes
Please don't edit files in the dist
subdirectory as they are generated via
grunt. You'll find source code in the src
subdirectory!
While grunt can run the included unit tests via PhantomJS, this shouldn't be
considered a substitute for the real thing. Please be sure to test the
test/*.html
unit test file(s) in actual browsers.
Release Checklist
- Make change to code
- Update version number in
OpenSearchlight.pkg.json
- In
README.md
update version numbers in Download and Release History sections - Run
grunt
and ensure all tests pass (rungit submodule update --init
first) - Run
grunt docs
to generate updated source documentation - Run
test/*.html
in the browser and ensure all tests pass - Check changes in to Git master
- Make changes to the
gh-pages
branch:- Add the new minified and development .js file
- Update index.html (and docco.css if necessary) from
dist/docs/OpenSearchlight-<VERSION>.html
Install and Build
This assumes you have node.js and npm installed already.
- Ensure all git submodules have been retrieved:
git submodule update --init
- Test that grunt is installed globally by running
grunt --version
at the command-line. - If grunt isn't installed globally, run
npm install -g grunt-cli
to install the latest version. You may need to runsudo npm install -g grunt-cli
. - From the root directory of this project, run
npm install
to install the project's dependencies. - Run
grunt
from the root directory to run the tests and build the packages and documentaion.
How to contact NSIDC
User Services and general information:
Support: http://support.nsidc.org
Email: [email protected]
Phone: +1 303.492.6199
Fax: +1 303.492.2468
Mailing address:
National Snow and Ice Data Center
CIRES, 449 UCB
University of Colorado
Boulder, CO 80309-0449 USA