edc-popover-react

This is a react implementation of edc popover displaying the contextual help

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

The required dependencies are:

ReactJS 16.4.0 or higher
FontAwesome 5.13.0 or higher
edc-client-js 3.1.3 or higher
edc-popover-utils 1.0.0 or higher

How to use

Import

You can import this module with npm by running:

npm install edc-popover-react --save

Or with yarn:

yarn add edc-popover-react

Setup

To work properly, this module needs a basic configuration, you must implement your own configuration by using a high-level Component PopoverProvider like the example below:

import { PopoverProvider } from 'edc-popover-react'
import { EdcHelp } from 'edc-popover-react'
...
 
<PopoverProvider
        pluginId='myedchelp'
        docPath='/doc'
        helpPath='/help'
        i18nPath='/doc/i18n'
      >
    ...
   <EdcHelp .../>
    ...
   <EdcHelp .../>
    ...
</PopoverProvider>

Props to specify for the PopoverProvider (see PopoverConfig) :

Prop	Type	Description
pluginId	`string`	The identifier of the target plugin documentation export
helpPath	`string`	The path to edc-help-viewer for opening the documentation. It needs to be the same as the base href parameter used by the viewer. See here for more information.
docPath	`string`	The path to exported documentation
i18nPath	`string`	The path to translation json files

Optional prop that can be overridden :

Method	Return type	Description	Default value
icon	EdcIconData	The icon (see Icons)	`far fa-question-circle`
lang	`string`	The default language	`en`
options	IPopoverOptions	Global popover options	see PopoverOptions
failBehavior	FailBehavior	The popover's behavior when an error occurs (see Behavior)	`{ popover: 'FRIENDLY_MSG', icon: 'SHOWN' }`

You can also reuse your provider to make your app more flexible (but not recommended) :

render(){
  return (
  ...
  <PopoverProvider
          pluginId='myedchelp'
          docPath='/doc'
          helpPath='/help'
          i18nPath='/doc/i18n'
        >
    ...
    <EdcHelp .../>
    ...
    <EdcHelp .../>
    ...
  </PopoverProvider>
  ...
  <PopoverProvider
          pluginId='myedchelp'
          docPath='/doc'
          helpPath='/help'
          i18nPath='/doc/i18n'
          icon='far corst'
        >
    ...
    <EdcHelp .../>
    ...
  </PopoverProvider>
  ...
  )
}

Usage

The main component is EdcHelp, you can use the component as follows:

import { EdcHelp } from 'edc-popover-react'
 
...
<EdcHelp mainKey='myKey' subKey='mySubKey'/>
...

All EdcHelp props that override the Provider are in the EdcHelp scope and completely isolated from other EdcHelps.

Props to specify for the EdcHelp (see EdcHelpProps):

Prop	Type	Description
mainKey	`string`	The main key of the contextual help
subKey	`string`	The sub key of the contextual help

Optional prop that can be overridden :

Method	Return type	Description	Default value
pluginId	`string`	A custom pluginId	`undefined` (keeps the pluginId from the provider)
lang	`string`	A language	`undefined` (keeps the language from the provider)
icon	EdcIconData	An icon (see Icons)	`undefined` (keeps the icon from the provider)
options	IPopoverOptions	Global popover options	see PopoverOptions

⚠️ All EdcHelp components must be surrounded by your configured provider (see Setup)

Customization

Fail behavior

You can customize the popover's behavior when an error occurs with the FailBehavior object.

There are separate behaviors for the help icon, and the popover itself. For the help icon when an error occurs:

SHOWN The help icon is shown as usual
DISABLED The help icon is greyed out
HIDDEN The help icon is completely hidden (but stays in DOM to avoid breaking the UI)
ERROR The help icon is replaced by an exclamation point (fas fa-exclamation-circle)

For the popover when an error occurs:

ERROR_SHOWN An error message is shown in the popover
FRIENDLY_MSG A friendly and translated message is shown in the popover
NO_POPOVER No popover appears when the help icon is triggered

By default, the icon is SHOWN and the popover is set to FRIENDLY_MSG.

⚠️ In case of a missing provider error or a wrong global configuration, an error is always shown !

Icons

The popover icons support 2 formats:

A CSS class (Font Awesome, Glyphicon, ...) using a <i />
An image which will have the same size as the text (height: 1em;) (PNG, JPG, SVG, ...) using a <img />

You can choose with the type prop:

class: The content must represent the CSS class
url: The content must represent the image's URL

If a string is provided to an EdcIconData, it will be interpreted as a CSS class by default.

CSS

Global

When dark-mode is enabled, the CSS class edc-on-dark is applied on the help icon.

So you can override this classes by CSS select the component as below sections and .edc-on-dark

(see EdcHelp.scss)

Popover

You can customize the popover's design as described in edc-popover-utils

Help icon

Each behavior (see Fail behavior) can be customized as below:

Behavior	CSS selector
`SHOWN`	`.edc-help-icon`
`DISABLED`	`.edc-help-icon-disabled`
`HIDDEN`	`.edc-help-icon-hidden`
`ERROR`	`.edc-help-icon-error`

(You can see the default values here)

Tests

Unit

edc-popover-react uses Jest and Enzyme for unit testing, you can test it by running:

npm test

yarn test

UI components

edc-popover-react uses Storybook for isolated UI components and features testing, you can test it by running:

npm run storybook

yarn run storybook

edc-popover-react