陈不易

Why#

The API documentation for openlayers is excellent, but using it can be quite challenging.

There are generally two ways to look up the API:

• Search engine 👉 openlayers + keyword 👉 open the specified link
• Open the API doc page 👉 search for the keyword 👉 reach the specified result through the search results

OL Search ¹#

OL Search is a browser extension (currently only available on Edge add-ons ²) that allows for quick searching of the openlayers API through the browser's address bar. The steps are as follows:

1. control+L or cmd+L to enter the search bar.
2. Enter the keyword ol, then tab or space to enter OL Search.
3. Enter the keyword for the target API (methods, member variables, triggers, etc.) and select the specified link to go directly.

Implementation#

Mainly divided into three steps:

Parsing the API Documentation#

https://openlayers.org/en/latest/apidoc/navigation.tmpl.html

The navigation bar of the documentation is embedded with HTML from the above address. There were originally two approaches.
One was to modify openlayers' own api build script to generate a set of JSON formatted API documentation information consistent with the above HTML content. However, considering two points:

• Maintenance issues; if this is done, each minor version update would require re-updating the plugin.
• Increased plugin size.
  The other approach was to directly parse the HTML navigation information file above. Here, I encountered a problem because in the browser extension, background.js cannot access the DOMParser object. I took a detour initially, using popup (the small window that appears when clicking the extension icon) to load data. This method had obvious drawbacks; after installing the plugin, users could not use it directly and had to click the extension icon and wait for the index file to initialize before using it. Later, I found a pure javascript DOM parsing library, which solved the problem.

Fuzzy Search#

Initially, I used hard search, which I was not satisfied with because occasional typos while typing are inevitable. Therefore, fuzzy search should be a necessity.
I referenced the approach from mdn-search and introduced fuse.js. I also made some enhancements for multiple keywords.
For example, when searching for the method readFeatures, various formats such as EsriJSON, KML, WKT, etc., all have the readFeatures method, and the default search result WKT appears later. If I want to find WKT's readFeatures, it would affect the experience.
By using fuse.js's search.$or, I implemented composite search for multiple keywords.
This way, simply entering readFeatures wkt will bring results containing WKT to the first candidate.

Remove Default Recommendations#

In the callback function listening to the address bar omnibox content change event, the browser will by default add a default recommendation before the recommended results you provide, with content being what you typed, and the address pointing to your extension's address plus that content. The default behavior is File not found.
This part of the idea comes from rust-search-extension. First, based on the user's input combined with the search results, the default recommendation is set to the original second result (the true first rank of search results). Then, after the user presses enter, it checks whether that option is the default suggestion; if it is, it points to the address of the true first rank of search results.

Finally#

I hope this tool helps colleagues who heavily use the openlayers API documentation.