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 |

:warning: 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.

:warning: 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

or

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

or

yarn run storybook