The classhelper acts as a search tool when filling an input field in the Roundup Issue Tracker. It is placed in a separate window to allow the user to interact with the page that includes the field. The implementation should be an HTML web component that wraps an existing classhelp link and provides a modern JavaScript/REST interface using vanilla JavaScript. If the user's browser does not support web components, it should fall back to the classhelp link.
Details
The Roundup Issue Tracker has a helper panel that allows the user to search for items to fill an input field. This search can be done using different criteria. For example a user search could be done by: username, the user's real name, the user's authorization role, or the user's email address. This is different from the usual auto-complete searches that search using only a single key field. Parameters from the underlying classhelper link will be parsed by the web component to use to create the interface. For example the parameters:
properties=username,realname,address: determines the fields displayed as part of the searchform=itemSynopsis- the id for the form whose property is being setproperty=nosy: the id (??) of the input field that should be updated when the classhelper is applied/closed.type=checkbox- the interface that should be shown. The 'checkbox' value allows selection by checkbox. If some other value is given (e.g. radiobutton), the web component should allow the existing classhelp link to be used.@sort=username- the field used to sort the found items@pagesize=50- the number of items to display. If there are more returned items than can be displayed, next/prev links to move among pages will be shown.
If form or property are missing, the
classhelper displays additional information about the class items. For
example if @properties=id,name,decription the description
propertyof the item would be displayed along with the id and name.
The query string is combined with the last element of the
path: /user or /issue to determine what
fields can be searched. Specification of available search fields is
not defined by a parameter in the wrapped link. So the web component
should support a "searchwith" attribute that takes a space (or comma)
separated list of property names that will be available for searching.
This is currently implemented using the obsolete HTML frameset and frame elements.
Roundup is meant to be customized by the owner. As a result we should not assume that the owner has a web development environment. So all core enhancements to Roundup should be relatively easy (add a few lines to an HTML template and drop in a JavaScript file or additional HTML templates) to deploy and not require third party libraries/frameworks.
The goal is to integrate this into all of the templates provided with Roundup and ship it with the July 2024 v2.4.0 release.
Also it should address the following issues with the classhelp component:
- with more than 50 items, the simple classhelp JavaScript windows do not allow to select from all items (affects keywords, superceder)
- Refactor use of javascript in templates to support Content Security Policy (CSP)
Also it will provide a basis for issue 2551260 replacing the classhelp/calendar system in the future. Parts of issue 2551260 are out of scope (calendar support, radiobutton support) for this project
Out of Scope
- It will not be applied to classhelp links that are used for dates. The calendar component of the classhelper is out of bounds for this project.
- It will not support radiobutton selection.
- It will support a restricted set of "searchwith" values indexed by class. (The REST interface doesn't supply a schema to the client by default. As a result, the client doesn't know how to prsent the search input: text, dropdown/select, numeric etc. These choices will be coded into a table (index class/attribute) in the component for the time being.)
Skills/Technologies Required/Excluded
- REST
- HTML web components which wrap existing HTML to provide fallback. Read more about HTML web components and how they differ from regular web components at the links below.
- vanilla JavaScript
- internationalization
Resources
- Roundup Issue Tracker Documentation
- REST interface Documentation for Roundup
- Errata for released documentation. If you are installing on windows, read this first.
- Go Make Things web development toolkit - examples of HTML Web Components: a toggle password visibility component. Also has other JavaScript templates and techniques. Author is also "the vanilla JavaScript guy".