search

readthedocs / readthedocs-sphinx-search

Deprecated: Enable search-as-you-type feature for docs hosted by RTD.
https://readthedocs-sphinx-search.readthedocs.io/
MIT License
33 stars 16 forks source link

Use an inline html template for search results and search result customization #117

Open agjohnson opened 2 years ago

agjohnson commented 2 years ago

In #116 Underscore was removed, and the pattern was shifted to native DOM manipulation.

One potential pattern to consider for future releases could be to use an HTML template inline in the output, as a Sphinx template. Effectively:

<html>
  <head>
    <script type="text/html" id="search-template">
      <div class="search__header">
        {{ _("Search results") }}
      <div class="outer__html">
        <div class="header">
          ...
        </div>
        ...
      </div>
    </script>
  </head>
</html>

This gives a template that can be targeted by our search JS, and manipulation of the template would happen with some data binding logic, or a more simple DOM search and replace.

The benefit here is that it is customizable at the Sphinx theme/template level, and can incorporate localization during the Sphinx build. Currently the search window will always be English. Localization is also possible in the JS now, but would have to be an additional step to be hooked into during building.

stsewd commented 2 years ago

This may interfere with the goal of making this a standalone js lib https://github.com/readthedocs/readthedocs-sphinx-search/issues/67.

But I'd be +1 on trying to create a small helper, we have a lot of nesting and could be confusing in the code... but I'd also love to simplify that https://github.com/readthedocs/readthedocs-sphinx-search/issues/118.

agjohnson commented 2 years ago

It shouldn't, this pattern would be usable as a standalone library as well. It would be a good way to provide more general support for templating the results, though not the only way to accomplish this.

stsewd commented 2 years ago

@agjohnson but we won't be able to use the sphinx's template engine or do you mean something like a string template?

agjohnson commented 2 years ago

Not a string template, but an isolated virtual DOM. That is, the default template might be an HTML file loaded through Webpack, and the customized template would be through a <script type="text/html"> block. Our manipulation of the template wouldn't be string operations though, but would be DOM operations. With a virtual DOM, it's even possible to do lightweight data binding and templating with something like Rivets.js.

In the case of Sphinx, but without playing with this, I can't say how we both expose this as a template and inject it in <head>. But hopefully the answer isn't a large hack.

stsewd commented 1 year ago

The other day I found out that HTML has the template tag https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template, so we can use that instead of a script tag.

agjohnson commented 1 year ago

Yup both work for this, the two options are rather comparable.