edc-popover-utils

A lightweight javascript edc popover for displaying the contextual help, based only on tippy.js.

This project is meant to be used with easy doc contents (aka edc).

edc is a simple yet powerful tool for agile-like documentation management.

Learn more at https://www.easydoccontents.com.

Dependencies

No extra dependency to install.

How to use

Import

You can import this module with npm by running:

npm install edc-popover-utils --save

Or with yarn:

yarn add edc-popover-utils

Setup

To build the popover, you need to provide the following configuration object:

/**
 * Configuration for the popover, passed as an input from the host element
 *
 * target: A reference of the target element that will trigger the popover
 * icon: The class name to use for the icon
 * content: The popover's content: the title for the header, the description, articles and links for the body
 * labels: The popover labels
 * options: Popover customizations
 */
export class PopoverConfig {
    target: Element;
    icon: string;
    content: PopoverContent;
    labels: PopoverLabels;
    options?: IPopoverOptions;
}

Content is the popover main items: title, description, articles and links:

/**
 * This class will contain the different content parts of the popover
 *
 * title: Will be set to the header
 * description: The description for the brick, under the title
 * articles: list of articles belonging to the brick
 * links: list of related documents, linked to this specific brick
 *
 */
export class PopoverContent {

    constructor(public title = '',
                public description = '',
                public articles: PopoverItem[] = [],
                public links: PopoverItem[] = []) {
    }
}

You just can call the constructor, passing the configuration object

const myPopoverInstance = new Popover(popoverConfig);

Available options are :

Property	Type	Description	Default
placement	popper.js PopoverPlacement	The popover placement	bottom
hideOnClick	boolean	If true, any click in the document will close the popover	true
interactive	boolean	Determine if we can interact with the popover content	true
trigger	string	Event that will trigger the popover: click mouseenter focus	click
customClass	string	class name that will be added to the main popover container	undefined
theme	string	Popover's theme name	undefined
displaySeparator	boolean	Show / Hide the line between header and body	true
displayTitle	boolean	Show / Hide the header containing the title - if false, will hide the separator	true
displayArticles	boolean	Show / Hide the articles section	true
displayRelatedTopics	boolean	Show / Hide the related Topics (aka Links) section	true
displayTooltip	boolean	Show / Hide the icon tooltip	true
displayPopover	boolean	If false, clicking on the icon will open the web help viewer on the first article, instead of showing the popover	true
delay	`number	[number, number]`	Delay in milliseconds before showing the popover - if array, delay for opening and closing respectively
animation	Animation	Adds a animation when opening / closing the popover	0
appendTo	`parent	Element	(() => Element)`

Customization

You can customize the popover with CSS classes as described below :

Tests

Unit

You can test the project by running:

npm run test

or

yarn test