edc-popover-ng
v5.8.0
Published
[![Build Status](https://travis-ci.org/tech-advantage/edc-popover-ng.svg?branch=master)](https://travis-ci.org/tech-advantage/edc-popover-ng) [![npm version](https://badge.fury.io/js/edc-popover-ng.svg)](https://badge.fury.io/js/edc-popover-ng)
Downloads
224
Keywords
Readme
edc-popover-ng
Angular popover component to display a contextual help.
This project is part of easy doc contents (edc).
edc is a simple yet powerful tool for agile-like documentation management.
Learn more at https://www.easydoccontents.com.
Compatibility
| Version | Angular | | ------- | -------- | | 5.1.1 | v7 - v10 | | 5.2.0 | v11 | | 5.3.0 | v12 | | 5.4.2 | v13 | | 5.5.0 | v14 | | 5.6.0 | v15 | | 5.7.0 | v16 | | 5.8.0 | v17 |
Dependencies
Required dependencies:
- Angular (v17)
- FontAwesome >= 4.7.0
How to use
Import
You can import this module with npm
by running:
npm install edc-popover-ng --save
Or with yarn
:
yarn add edc-popover-ng
Add font-awesome as a dependency
npm install font-awesome --save
In your main style file (e.g. style.less) :
@import "~font-awesome/less/font-awesome.less";
Setup
Provide a service implementing PopoverConfigurationHandler
Edc Help module needs a basic configuration.
To provide this configuration, first create a new Service implementing PopoverConfigurationHandler.
Methods to implement are :
| Method | Return type | Description | |---|---|---| | getPluginId | string | The identifier of the target plugin documentation export | | getHelpPath | string | The path to edc-help-ng application | | getDocPath | string | The path to exported documentation | | getI18nPath | string | The path to translation json files |getPopoverOptions | getPopoverOptions | IEdcPopoverOptions | Options for the popover |
Example :
import { Injectable } from '@angular/core';
import { EdcPopoverConfiguration, PopoverConfigurationHandler } from 'edc-popover-ng';
@Injectable()
export class YourService implements PopoverConfigurationHandler {
getPluginId(): string {
return 'edchelp';
}
getHelpPath(): string {
return '/help';
}
getDocPath(): string {
return '/doc';
}
getI18nPath(): string {
return '/doc/my-i18n-directory';
}
getPopoverOptions(): IEdcPopoverOptions {
// return the global scope options. They can be overwritten at component level.
return {
placement: 'left'
};
}
}
N.B : The choice to provide a service instead of an object has been made to be more dynamic.
For instance you could inject the Http
service in YourService
to get configuration from remote (see also : https://aclottan.wordpress.com/2016/12/30/load-configuration-from-external-file/).
Import HelpModule
In your main application module, for example AppModule
:
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
// Import edc-popover-ng library elements.
import { HelpModule, PopoverConfigurationHandler } from 'edc-popover-ng';
// Import your service implementing PopoverConfigurationHandler.
import { YourService } from './path.to.your.service';
@NgModule({
declarations: [
AppComponent
],
imports: [
// Specify the edc-help module as an import, and provide service implementing PopoverConfigurationHandler.
HelpModule.forRoot({
configLoader: {provide: PopoverConfigurationHandler, useClass: YourService}
}),
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
You can now use the Help component in your Angular application :
<h1>
{{title}}
<edc-help [mainKey]="'my.mainKey'" [subKey]="'my.subkey'" [placement]="'bottom'" [lang]="'en'"></edc-help>
</h1>
If your application uses more than one documentation
Your application might rely on more than one documentation.
You can then specify a custom documentation plugin Id using the optional pluginId
attribute in the edc-help component.
<h1>
{{title}}
<edc-help [pluginId]="'my.specificPluginId'" [mainKey]="'my.mainKey'" [subKey]="'my.subkey'">edc-help>
</h1>
Inputs and options
Mandatory inputs
Mandatory inputs or the EdcHelp
(see HelpComponent):
| Prop | Type | Description |
|---|---|---|
| mainKey | string
| The main key of the contextual help |
| subKey | string
| The sub key of the contextual help |
Optional inputs
Optional inputs for the component:
| Input Name | Return type | Description | Default value |
|---|---|---|---|
| pluginId | string
| A different pluginId from the one defined in the main service | undefined
|
| lang | string
| The language to use, for labels and contents, identified by the 2 letters from the ISO639-1 standard. Will use documentation's default if no value is provided | undefined
|
| options | EdcPopoverOptions | Options for this popover - will overwrite global options | undefined
|
Available options (EdcPopoverOptions):
| Property | Type | Description | Default |
|---|---|---|---|
| icon | PopoverIcon
| Icon settings, see Icon | PopoverIcon |
| failBehavior | FailBehavior
| Icon and popover behavior on error, see Fail Behavior | FailBehavior |
| placement | popper.js Placement
| Popover positioning relatively to the icon | bottom
|
| hideOnClick | boolean
| If true, any click outside of the popover will close it (inside too if interactive is false) | 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 |
| dark | boolean
| Dark mode | false
|
| theme | string
| Popover's theme name | undefined
|
| displayPopover | boolean
| Show the popover / Go directly to the web help viewer on click | true
|
| displaySeparator | boolean
| Show / Hide the separator between header and body | true
|
| displayTitle | boolean
| Show / Hide the header containing the title | 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
|
| delay | number | [number, number]
| Delay in milliseconds before showing the popover - if array, delay for opening and closing respectively | undefined
|
| animation | Animation
| Animation when opening / closing the popover | undefined
|
| appendTo | 'parent' | Element | (() => Element)
| The element to which append the popover to | (() => documentation.body)
|
Icon
PopoverIcon contains the options for the icon.
| Property | Type | Description | Default |
|---|---|---|---|
| class | string
| Class name for the icon. Font awesome icon classes are handled natively | 'fa fa-question-circle-o'
|
| url | string
| Image url, size is determined by height, and width properties | undefined
|
| height | number
| Image height in pixels (for url images only) | 18
|
| width | number
| Image width in pixels (for url images only). Will take height value if none is provided | 18
|
If class
property is provided, it will overwrite the default class 'fa fa-question-circle-o'
.
If url
is defined, it will override the class property, even if class
is defined.
Fail behavior
If the help content failed to be loaded - or any other error occured, the icon and the popover will look for the FailBehavior options to define their style and content.
There are separate behaviors for the help icon, and the popover itself.
For the help icon when an error occurs, it adds the following css selector.
| Behavior | Description | CSS selector |
|---|---|---|
| SHOWN
| The help icon is shown as usual (default) | .edc-help-icon
|
| DISABLED
| The help icon is greyed out | .edc-icon-disabled
|
| HIDDEN
| The help icon is completely hidden (but stays in DOM to avoid breaking the UI) | .edc-icon-hidden
|
| ERROR
| The help icon is replaced by an exclamation point | .edc-icon-error
|
Default values are in file help.less
For the popover when an error occurs:
ERROR_SHOWN
An error message is shown in the popoverFRIENDLY_MSG
A friendly and translated message is shown in the popoverNO_POPOVER
No popover appears when the help icon is triggered
By default, the icon is SHOWN
and the popover is set to FRIENDLY_MSG
.
Customization
CSS
Global
When dark-mode is enabled, the CSS class edc-on-dark
is applied to the help icon.
Popover
You can customize the popover with CSS classes as described below :
For more control, the customClass
option will add the given class name to the popover container .edc-popover-container
.
You can then override the main classes.
For example, if you'd like to change the background color of the popover
.my-custom-class {
background-color: lightgreen;
}
/* or the title font-size */
.my-custom-class .edc-popover-title {
font-size: 18px;
}
Providing your own translations for the popover labels
You can set additional translations (or replace the existing ones) by adding i18n json files to the documentation folder.
Please note that one file is required per language (see file example below), and should be named following the ISO639-1 two letters standards (ie en.json, it.json...).
By default, edc-popover-ng will be looking for the files in [yourDocPath]/popover/i18n/ (*.json), but you can change this path by modifying getI18nPath() in your PopoverConfigurationHandler.
edc-popover-ng comes with English and French translations, and supports up to 36 languages. For the full list, please refer to LANGUAGE_CODES.
JSON file structure
Here is the en.json file used by default:
{
"labels": {
"articles": "Need more...",
"links": "Related topics",
"iconAlt": "Help",
"comingSoon": "Contextual help is coming soon.",
"errorTitle": "Error",
"errors": {
"failedData": "An error occurred when fetching data !\nCheck the brick keys provided to the EdcHelp component."
},
"content": null,
"url": "",
"exportId": ""
}
}
Customization
You can customize the popover with CSS classes as described below :