陈不易

Why#

The content of the openlayers API documentation is excellent, but using it can be challenging.

There are generally two ways to search for APIs:

• Search engine 👉 openlayers + keywords 👉 Open the specified link
• Open the API doc page 👉 Search for keywords 👉 Reach the specified result through search results

OL Search ¹#

OL Search is a browser extension (currently only available on Edge add-ons²) that allows you to quickly search for openlayers APIs through the browser's address bar. Here are the steps:

1. Press control+L or cmd+L to enter the search bar.
2. Enter the keyword ol, press tab or space to access OL Search.
3. Enter the keyword for the target API (method, member variable, trigger, etc.) and select the specified link to go directly to it.

Implementation#

It mainly consists of three steps:

Parsing the API documentation#

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

The navigation bar of the documentation is embedded with an HTML from the above address.
There were originally two ideas here.
One is to generate a set of JSON-formatted API documentation information that is consistent with the above HTML content by modifying the openlayers' own api build script.
But considering two points:

• Maintenance issues. If we do this, the plugin needs to be updated for every minor version update.
• Increased plugin size.
  The other approach is to directly parse the navigation information file of the above HTML. However, there was a problem here because the DOMParser object cannot be accessed in the background.js of the browser extension. I took a detour and initially loaded the data through the popup (a small window displayed when clicking the extension icon). This approach has an obvious drawback: users cannot use it directly after installing the plugin. They need to click the extension icon and wait for the index file to initialize before they can use it. Later, I found a pure javascript DOM parsing library, which solved this problem.

Fuzzy search#

At the beginning, I used exact search, but I was not satisfied with it even when using it myself because occasional typos are inevitable when typing. Therefore, fuzzy search is a must-have.
Here, I referred to the approach of mdn-search and introduced fuse.js. I also made some enhancements for multiple keywords.
For example, when searching for the method readFeatures, there are various formats such as EsriJSON, KML, WKT, etc., all of which have the readFeatures method. However, the default search result has WKT at the end. If I want to find readFeatures for WKT, it would affect the user experience.
By using search.$or in fuse.js, I achieved compound search with multiple keywords.
So now, by simply entering readFeatures wkt, the result containing WKT will be brought to the top.

Disabling default suggestions#

In the callback function for listening to changes in the address bar omnibox content, the browser defaults to adding a default suggestion in front of the recommendations you provide. Its content is what you typed, and the address it points to is the address of your extension plus that content. The default behavior is File not found.
This idea comes from rust-search-extension. First, based on the user's input content combined with the search results, the default suggestion is set to the original second result (the first priority of the actual search results). Then, after the user presses Enter, it checks whether the selected option is the default suggestion. If it is, it points to the address of the first priority of the actual search results.

Finally#

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