Modernized help UI

This prototype is based on HTML 5 with an iframe for the content and, unlike the legacy UI, does not use HTML 4 framesets. Technically, it sits on top of the legacy UI. For example, when doing a full search, the HTML page of the legacy UI will be parsed and rendered in the web browser (widget) using JavaScript. This has disadvantages, but it has made it easier to develop this prototype as a plugin without the need to patch Eclipse.

Once the new UI no longer requires anything from the legacy UI and is no longer lagging behind in terms of internationalization and accessibility, the legacy UI can be deprecated and removed: see Further development below.

Improvements compared to the legacy UI:

• Responsive, e.g. by automatically hiding the TOC bar on small screens
• Search as you type and auto completion of search terms
• Topic preview when hovering over instant search results
• Search scopes drop-down in the search field to search in all books, in the current book, in the current chapter or in a user-defined scope
• Full search results shown as a page instead of as side bar
• Full search results can be filtered by books
• Infocenter: UI designed aware of mobile devices
• Infocenter: URL contains topic or search, so a deep link can be bookmarked or shared in the usual way

Activation

This prototype can be activated with the following Java property:

-Dorg.eclipse.help.webapp.experimental.ui=true

To test, modify and/or customize this prototype, the files in this folder can be put in a separate plugin (in index.html the links to the JavaScript and CSS file have to be changed from m/... to something like rtopic/com.example.my_plugin/...) and activated as follows (assuming the plugin has the symbolic name com.example.my_plugin; using the raw topic help link rtopic/<plugin>/<optional-path>/<file>):

 -Dorg.eclipse.help.webapp.experimental.ui=<plugin>/<optional-path>/<file>

For example, when the plugin has the symbolic name com.example.my_plugin with index.html in the folder customized-help:

 -Dorg.eclipse.help.webapp.experimental.ui=com.example.my_plugin/customized-help/index.html

The m/index.js JavaScript file can be customized in the same way:

 -Dorg.eclipse.help.webapp.experimental.ui.js=<plugin>/<optional-path>/<file>

The customized HTML and JavaScript file can contain placeholders (see org.eclipse.help.internal.webapp.HelpUi.resolve(String, HttpServletRequest)).

Further development

Unsorted list of things to improve and where the legacy UI is currently used:

• Create the page dynamically to avoid a callback to determine the mode, whether Infocenter or Eclipse embedded help (the latter with previous/next navigation buttons and bookmark support) and to determine the initial content page.
  • /advanced/tabs.jsp
  • /advanced/content.jsp
• Return search results directly as HTML page instead of parsing and re-rendering legacy HTML page
  • /advanced/searchView.jsp
• Print chapter
  • /advanced/print.jsp
• Rest API to get the following as JSON instead of requesting and parsing the legacy UI
  • Search as you type and search term completion: currently, when typing fo, a search is executed for fo* (which means starts with fo), but this disables stemming like in the full search (which means when entering logging, pages containing log or logs are not found; ideally starts with and stemming should be combined; the search term completion proposals are currently computed from the words contained in the results, for which there are better ways to do this on the server side
    • /advanced/searchView.jsp
  • User-defined search scopes
    • /advanced/workingSetManager.jsp - list of scopes
    • /advanced/workingSetState.jsp - add, edit or remove a scope
    • /scopeState.jsp - set or unset scope
  • Bookmarks
    • /advanced/bookmarksView.jsp
  • Storing UI settings: TOC side bar width and show/hidden, search results filter tree expanded or collapsed, etc.
• Things to improve (where this prototype currently falls behind the legacy UI):
  • Right-to-left (RTL) support
  • Accessibility (HTML5 ARIA, keyboard support, color contrast, etc.)
  • Dark theme support
  • User-defined search scope:
    • Prevent to create an empty scope
    • Activate search scope on creation
  • Printing via shortcut (Ctrl+P) should print the content only, even when the focus is outside the content (e.g. in the search field)
  • Bookmarks: adding a bookmark should be more intuitive
  • Customization, e.g. to be able to specify an Infocenter (header/banner, footer, etc.): support of legacy options
  • ...
• By default redirect via .../index.jsp#topic/... instead of via .../index.jsp?topic=..., but still support such legacy links
• ...

Design decisions and debugging hints

To use a web browser for debugging, specify a fixed port for the help server, e.g. -Dserver_port=49999, in Eclipse open the help window (Help > Help Contents) and in the web browser open one or more of the following pages:

• Modernized UI: http://127.0.0.1:49999/help/index.jsp
• Legacy UI: http://127.0.0.1:49999/help/index.jsp?legacy

Drop of Index tab

The Index tab of the legacy UI was dropped in favor of a simpler UI.

Browser support

On the one hand state of the art should be used, on the other hand as many browsers as possible should be supported.

→ Support browsers that support Flexbox (98.74%): Chrome 21, Internet Explorer 10, Firefox 22, Android Browser 21, etc. and higher

See:

• Browser support
• Tutorial/specification: CSS, JavaScript
• JavaScript minifiers:
  • https://javascript-minifier.com/
  • https://javascriptminifier.com/

General layout (CSS): Flexbox (tutorial, 98.74%)

• Instead of float, layout via tables (both are deprecated for that) and gridx (since it is too new and not yet widely supported)
• If needed, consider add fallback for IE 6-9 (see Flexbox Fallbacks)

Navigation and deep linking

Going back in the browser history can cause issues in combination with deep linking, since the navigation is done in the iframe except for the search page which is not shown in the iframe. The problem is that when going back to a search page, the search might need to be submitted again and for this the query must be known.

Ways that don't work:

• Deep link containing query as hash of the top window (...#q=...) set via history.pushState(...): top window hash might not be restored when navigation happens also in the content iframe
• Query as hash or as query of the content iframe set via history.pushState(...): conflicts with existing hashes/queries of content pages and does not work with external content pages
• Data URL used in content iframe containing the query: not allowed in Internet Explorer for security reasons

Chosen solution:

• For full search set content iframe instead of doing a remote request and get result from live DOM of the iframe when loaded

Search

• Without interim results displayed semi-transparent since this is only helpful in rare cases (very slow responds and previous cached query containing hits of current query)

To simulate a slow response replace return function(data) { with

                return function(data) {
setTimeout(function(data) { return function() {processData(data)}}(data), 1000);
};
function processData(data) {

Issues caused by <iframe>

To catch mouse and click events (for slider and drop-down menues) add an overlay element covering the whole page (see createOverlay()).

Debug overlay by adding the following line after the line overlayStyle.width = '100%';:

overlayStyle.background = 'rgba(200, 100, 100, .2)';