Help inline button
Use when
Use help inline buttons to invoke help content that users don't need to see every time or that is too long for persistent inline help. This provides access to supplementary information while avoiding most of the visual noise that comes with persistent inline help.
Use help inline buttons when users may need initial assistance but:
- The tasks are performed frequently.
- Ramifications of mistakes are small.
Don't use when
Don't use help inline buttons when a small amount of persistent inline text can help users understand tasks. Use persistent inline help instead when:
- Tasks are complex and performed infrequently.
- User actions have far-reaching consequences that are not obvious.
Popover
Display help content in popovers when a small amount of user assistance content is valuable some of the time. For larger amounts of user assistance, use the helpKey
Help widget or other container
For longer help content that doesn't fit in popovers, use the helpKeyhelpKey
Page-level and modal-level help
For complex tasks where users need comprehensive documentation, they invoke help at the page or modal level.
In Blackbaud solutions, users invoke help from the omnibar or a modal heading. To display context-sensitive help content, Blackbaud developers use the help widget, which is for internal Blackbaud use only.
Element-level help
Place the help inline button to the right of the label for the element that the help content supports.
Guidelines
Components
- NPM package
@skyux/help-inlineView in NPM | View in GitHub None found.- Install with NPM
npm install --save-exact @skyux/help-inlineNone found.
import { SkyHelpInlineModule } from '@skyux/help-inline';
Selector: sky-help-inline
Inserts a help button beside an element, such as a field, to display contextual information about the element.
Inputs
ariaControls: string | undefined
The ID of the element that the help inline button controls.
This property supports accessibility rules for disclosures.
For more information about the aria-controls attribute, see the WAI-ARIA definition.
ariaExpanded: boolean | undefined
Whether an element or popover controlled by the help inline button is expanded. If popoverContent is specified, this value is overridden with popover expanded status.
ariaLabel: string | undefined
The ARIA label for the help inline button. This sets the button's aria-label to provide a text equivalent for screen readers.
Will be overridden if label text is set.
Default: "Show help content"
helpKey: string | undefined
A unique key that identifies the global help content to display when the button is clicked.
labelText: string | undefined
The label of the component the help inline button is attached to.
popoverContent: string | TemplateRef<unknown> | undefined
The content of the help popover. When specified, clicking the help inline button opens a popover with this content and optional title.
popoverTitle: string | undefined
The title of the help popover. This property only applies when popoverContent is
also specified.
Outputs
actionClick: EventEmitter<void>
Fires when the user clicks the help inline button.
Provides methods for opening and updating a globally accessible help dialog.
Properties
widgetReadyStateChange: Observable<boolean>
Emits when the help widget ready state changes.
Methods
openHelp(args?: SkyHelpOpenArgs): void
Opens a globally accessible help dialog.
Parameters
args?: SkyHelpOpenArgs
The options for opening the help dialog.
Returns
void
updateHelp(args: SkyHelpUpdateArgs): void
Updates a globally accessible help dialog.
Parameters
args: SkyHelpUpdateArgs
The options for updating the help dialog.
Returns
void
Options to apply to all components that invoke global help.
interface SkyHelpGlobalOptions {
ariaControls?: string;
ariaHaspopup?: "dialog" | "menu" | "listbox" | "tree" | "grid";
}Properties
ariaControls?: string
The ID of the element that is displayed when the invoking component is clicked.
ariaHaspopup?: "dialog" | "menu" | "listbox" | "tree" | "grid"
The type of popup triggered by the invoking component.
Options for displaying a globally accessible help dialog.
interface SkyHelpOpenArgs {
helpKey: string;
}Properties
helpKey: string
A unique key that identifies the help content to display.
Options for updating a globally accessible help dialog.
interface SkyHelpUpdateArgs {
helpKey?: string;
pageDefaultHelpKey?: string;
}Properties
helpKey?: string
A unique key that identifies the current help content to display. If set to undefined, the page's default help content will be displayed.
pageDefaultHelpKey?: string
A unique key that identifies the page's default help content to display. Set this property to undefined to unset the current page default help key.
SKY UX test harnesses are built upon Angular CDK component harnesses. For more information see the Angular CDK component harness documentation.
import { SkyHelpInlineHarness } from '@skyux/help-inline/testing';
Harness for interacting with a help inline button component in tests.
Methods
click(): Promise<void>
Clicks the help inline button.
Returns
Promise<void>
getAriaControls(): Promise<null | string>
Gets the aria-controls value.
Returns
Promise<null | string>
getAriaExpanded(): Promise<boolean>
Gets the aria-expanded value.
Returns
Promise<boolean>
getAriaLabel(): Promise<null | string>
Gets the aria-label value.
Returns
Promise<null | string>
getLabelText(): Promise<undefined | string>
Gets the label text.
Returns
Promise<undefined | string>
getPopoverContent(): Promise<undefined | string>
Gets the help popover content.
Returns
Promise<undefined | string>
getPopoverTitle(): Promise<undefined | string>
Gets the help popover title.
Returns
Promise<undefined | string>
SkyHelpInlineHarness.with(filters: SkyHelpInlineHarnessFilters): HarnessPredicate<SkyHelpInlineHarness>
Gets a HarnessPredicate that can be used to search for a
SkyHelpInlineHarness that meets certain criteria.
Parameters
filters: SkyHelpInlineHarnessFilters
Returns
HarnessPredicate<SkyHelpInlineHarness>
A set of criteria that can be used to filter a list of SkyHelpInlineHarness instances.
interface SkyHelpInlineHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
import { SkyHelpTestingModule } from '@skyux/core/testing';
Mocks SkyHelpService to enable testing of global help.
Provides methods for validating global help in unit tests.
Methods
closeHelp(): void
Close the current help.
Returns
void
expectCurrentHelpKey(expectedHelpKey: string | undefined): void
Validates the current help key and throws an error if the current help key does not match the expected help key.
Parameters
expectedHelpKey: string | undefined
The expected help key.
Returns
void
Loading...