Wikidata/Development/Entity selection widget design

From Meta, a Wikimedia project coordination wiki

Refers to bugzilla:40393.

Task: Design a widget that allows to select an entity

The entity selection widgets can be chosen to select either an item or a property, i.e. it tells the API wether it is looking for an item or a property, and the API only provides appropriate options.

The API being used is the one described here bugzilla:40392. Any requirements to that API should be captured in that bug.

It sends the current text in the widget to the API, the entity type, and the language along with offset and limit parameters, and gets back a list of hits. Each hit has an ID, a label (optional, if existing), a description (optional, if existing), and an alias (optional and only if matching against it).

It behaves like a dropdown list. Each field of the dropdown list represents one hit and shows:

  • the label (bold) - if no label is given the ID is shown here
  • the description - if no description is given, this line is skipped
  • the alias, if hitting on the alias (with a prefix like "Also known as", just as in the item view)

The widget returns the ID of the selected entity if successful.

Do not bold the hit part.

Make the widget depend only on jQuery. Please. No MediaWiki dependencies.

Answering some questions[edit]

  • What to do with long labels / descriptions / aliases? Long lines in the suggestion list will be faded out towards the end. The suggestion list will be made resizable. As additional feature, a detailed pop-out box right next to a selected item may be offered when hovering a suggestion or clicking a certain hint/icon (for mobile).
  • What about bolding? Don't bold besides bolding the label. Do not bold on the hit.
  • What about long result sets? Make the drop-down list scrollable. A "more" link at the bottom of the suggestion list will be used to fetch a fixed number of additional suggestions. If the number of exact matches is lower than the number of suggestions fetched when clicking "more", at least that fixed number of suggestions shall be presented. Ensure that the "more" link only gets shown when there actually are more items. The very last field at the bottom is the "Create new" link. It shall be possible to disable/hide the "Create new" link. For example, when having an exact match on a property, the "Create new" link has to be disabled. Also if there are more exact matches than are shown, "Create new" should be disabled.
  • Where does the "Create new" link go? It is always the bottom-most field in the drop-down list. Do not display it fixed at the bottom, but part of the scrollable results. There is no reason for someone to select "Create" before having seen all (exact) matches.

Behavior of keys and selection[edit]

  • Typing letters, delete, etc. changes the value of the text field of the dropdown list, and thus also the offered hits.
  • The first hit is selected after a change of value in the text field
  • Pressing cursor down or up lets the user select another field
  • Pressing return or tab locks the selection and displays the label of the selected hit (or the ID, if no label exists)
  • Pressing ESC when having highlighted some suggestion will return the focus to the input box and reset its text to the one entered originally; Pressing ESC when the focus is on the input box, nothing shall happen but a callback will be offered that other developers may attach to.

The widget will be part of bigger widgets (like the "add statement" widget), wherein actions like ESC or return will trigger different events and thus need to bubble up the notification chain.

Scrum items[edit]

  1. Make wikibase.autocomplete perfectly independent from wikibase (5)
  2. Adapt wikibase.autocomplete to required data structure (3)
  3. Section layout for suggestion list (5)
  4. Highlight first suggestion when auto-completing (3)
  5. Constrain suggestion list width (3)
  6. "Create new" link (2)
  7. "More" link (3)
  8. ESC key behaviour (3)
  9. Improve auto-complete appearance (2)
  10. Make suggestion list width resizable (5)