On Tue, 23 Nov 2021 15:11:33 GMT, Hannes Wallnöfer <[email protected]> wrote:
> Please review a new feature to trigger a javadoc search on any javadoc page > through a specially encoded URI fragment. > > This allows the search feature to be triggered "locally" in the currently > viewed page by clicking on a link to the search fragment, or "remotely" by > linking to a page whose URI includes a search fragment. The search fragment > uses the following syntax to make it differ from normal page anchors: > > #!search=search_term > > Although fragments are most commonly used to target elements by their `id` > attribute in HTML documents they are by no means limited to this. The [URI > specification] defines the fragment in very generic terms as additional > information identifying some secondary resource within the primary resource > identified by the URI. There are also many examples of [proposed and existing > uses] of fragment identifiers for similar tasks. > > [URI specification]: https://datatracker.ietf.org/doc/html/rfc3986#section-3.5 > [proposed and existing uses]: > https://en.wikipedia.org/wiki/URI_fragment#Proposals > > I considered other mechanisms such as query strings or javascript links, but > they all have significant drawbacks compared to URI fragments. Query strings > are usually associated with server side processing and cannot be opened > without reloading the page. Javascript links on the other hand cannot be > triggered remotely as part of the primary URI, and there are security issues > associated with them. I think URI fragments are the right tool for the task. > > The new feature is deployed in the [Help page] with the search examples, > which should help to popularize the feature. Additionally it should be > documented in the javadoc search spec, for which I'll file a separate JBS > issue. > > [Help page]: http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html > > Below are the URIs for the search examples in the Help page as well as a few > other examples: > > http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=j.l.obj > http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=InpStr > http://cr.openjdk.java.net/~hannesw/8248863/api.00/help-doc.html#!search=HM.cK > http://cr.openjdk.java.net/~hannesw/8248863/api.00/index.html#!search=stringbuilder.append > http://cr.openjdk.java.net/~hannesw/8248863/api.00/index.html#!search=java%20collection%20framework I guess I would recommend the following: 1. Use query syntax, not fragment syntax 2. Support this feature only on the top level page, so that the proposed search URL is of the form `https://host:port/path/to/api?search=query-string` ... related: this is a publicly visible spec and needs a CSR (this is true whatever form of URL is used.) 3. If the search returns a single unique result, select that page and show the matching element. If the search does not yield a single result, I'm OK to show the top level page with the search-result-menu open. I'm OK with not creating a dedicated search landing page, at least for remotely generated queries, but the more you push on local search (e.g. to link to a set of methods) the more useful a dedicated multiple-results page might become. Right now, the use of the popup menu for a search URL seems more like a workaround for an inadequate query, than a feature to display multiple search results. I still don't find the argument for local search links very compelling. I find the argument to support local search links on the same page even less compelling. I don't like the dual use of fragments for both "traditional" navigate-to-id and the proposed "search". Your justification in terms of JavaScript is an admission to the internal implementation. Documenting the URL format in spec docs and a CSR is going to be ... well, ... icky. I note that with 1-2-3 above, you could still "demo" the search-url feature on the `help-doc.html` page, for both unique results and multiple results. ------------- PR: https://git.openjdk.java.net/jdk/pull/6524
