Contextual Help in Horizon UI

Registered by Swaroop Jayanthi

This blueprint has been superseded. See the newer blueprint "Context-Sensitive Help" for updated plans.

This is a development / implementation proposal for OpenStack’s UX blueprint titled “Suggest Ways to Add Contextual Help to Horizon”.

Description
In a Cloud OS environment, a Cloud Admin or a Cloud Operator should quickly understand what each field on a form means and expects as input, thus easing his intellectual / memory load while facilitating an efficient task performance.

Contextual / inline form field help in existing Horizon UI is not uniform for all input fields, is inconsistent and varying. There are auto pop-ups (on some input text fields), inline static help text, pop-ups that appear on-mouse-over a help (?) icon, help manuals and probably lots of other ways of providing additional help throughout the application.

To streamline contextual help display for all form fields, Openstack UX team came up with some interaction design proposals. One important goal of this effort is to arrive at a common interaction solution to provide contextual help for any / all types of input elements (input box, drop list, checkbox, etc.) – and that:

1. Enhances user’s interaction experience
2. Makes better use of dialog’s real estate
3. Is clean and reduces clutter
4. Is persistent as long as the user works on a widget
5. Is effortless – unlike the “?” where one needs (avoidable) motor performance to see help text

“Suggest Ways to Add Contextual Help to Horizon” proposes 3 design approaches of which Design# 3 is approved for implementation.

Proposed Implementation
For each field in the Horizon UI:
1. Each form in Openstack_dashboard is constructed by extending Horizon forms.
2. Currently Horizon supports built in forms as mentioned below:
a. SelfHandlingForm
b. DateForm
These forms are part of Horizon framework (horizon/horizon/forms/base.py)
3. ‘help_text’ attribute should be set for each form field in Openstack_dashboard implementation if the forms extending SelfHandlingForm or any built in forms of Horizon.
4. In the Horizon UI template layer, when the mouse over on a Form field, the inline help text will should be displayed, this can be achieved by changing the rendering part of help_text attribute of each form field in the below location of template (horizon/horizon/templates/horizon/common/_bootstrap_form_field.html)
5. When the mouse over show a panel on the rightside of the form field with help_text rendered.

Features
• No static display of help text
• Help text displays as the user ‘moves’ to focus on an input widget - using either mouse or via Tab key navigation, and is visible as long as he works with that widget
• No deliberate mouse-over effort required here
• This interaction behavior is common across all input widget types on a form
 Limitations
• For all existing form fields, contextual help will be displayed if help text already available, else the field is ignored
• ‘Learn more‘ as mentioned in the UX blueprint design will not be implemented

References
• Baseline OpenStack UX blueprint –
https://blueprints.launchpad.net/openstack-ux/+spec/contextual-help-horizon
• UX designs write-up - https://www.dropbox.com/s/fzitkei90i31kti/Ways%20to%20Add%20Contextual%20Help%20to%20Horizon.pdf
• UX designs – https://www.dropbox.com/s/ei56d8ffggs1h51/ContextualHelpInHorizon_Proposal_v1.zip
(You need to download this file, unzip and open "start.html" / "index.html" in your browser to run the interactive prototype)

Blueprint information

Status:
Complete
Approver:
None
Priority:
Undefined
Drafter:
Swaroop Jayanthi
Direction:
Needs approval
Assignee:
Swaroop Jayanthi
Definition:
Superseded
Series goal:
None
Implementation:
Unknown
Milestone target:
None
Completed by
Matthias Runge

Related branches

Sprints

Whiteboard

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.