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

yarn test

edc-popover-utils