Merge pull request #5 from tech-advantage/feature/edc-2648

tech-advantage · Nov 9, 2020 · cf0f5b8 · cf0f5b8
2 parents 65a5a64 + 30e6bdf
commit cf0f5b8
Show file tree

Hide file tree

Showing 45 changed files with 2,742 additions and 824 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -128,12 +128,8 @@ module.exports = {
             "error",
             "rxjs"
         ],
-        "no-shadow": [
-            "error",
-            {
-                "hoist": "all"
-            }
-        ],
+        "no-shadow": "off",
+        "@typescript-eslint/no-shadow": ["error"],
         "no-throw-literal": "error",
         "no-trailing-spaces": "off",
         "no-undef-init": "error",

diff --git a/CSSClasses.png b/CSSClasses.png
diff --git a/CSSClasses.psd b/CSSClasses.psd
diff --git a/README.md b/README.md
@@ -3,9 +3,9 @@
 [![Build Status](https://travis-ci.org/tech-advantage/edc-popover-ng1.svg?branch=master)](https://travis-ci.org/tech-advantage/edc-popover-ng1)
 [![npm version](https://badge.fury.io/js/edc-popover-ng1.svg)](https://badge.fury.io/js/edc-popover-ng1)
 
-AngularJS implementation of edc popover displaying the contextual help.
+AngularJS popover component to display a contextual help.
 
-_This project is meant to be used with **easy doc contents** (aka edc)._
+_This project is part of **easy doc contents** [(edc)](https://www.easydoccontents.com)._
 
 edc is a simple yet powerful tool for agile-like documentation management.
 
@@ -15,8 +15,8 @@ Learn more at [https://www.easydoccontents.com](https://www.easydoccontents.com)
 
 The required dependencies are:
 
-- [AngularJS](https://https://angularjs.org/) tested with 1.5.8 and higher
-- [FontAwesome](https://github.com/FortAwesome/Font-Awesome) 4.7.0 or higher
+- [AngularJS](https://https://angularjs.org/) >= 1.5.8
+- [FontAwesome](https://www.npmjs.com/package/font-awesome) 4.7.0
 
 ## How to use
 
@@ -38,20 +38,28 @@ import the css file in your main style file (e.g. _style.less_) :
 @import '~edc-popover-ng1/dist/edc-popover-ng1.css';
 ```
 
-font-awesome is a dependency; if you use scss, you'll need to specify the font localisation too
+You need to [download font-awesome](https://fontawesome.com/v4.7.0/get-started/) or install it as a dependency
 
-```scss
-$fa-font-path: '~font-awesome/fonts/';
+```bash
+npm install font-awesome --save
 ```
+Then import the style.
+```html
+<link rel="stylesheet" href="path/to/font-awesome/css/font-awesome.min.css">
+```
+Note that if you use scss, you'll need to specify the font localisation too, defining the `$fa-font-path` variable
 
-```less
-@import "~font-awesome/less/font-awesome.less";
+```scss
+$fa-font-path: '~font-awesome/fonts/';
+@import '~font-awesome/scss/font-awesome';
 ```
 
+More info [here](https://fontawesome.com/v4.7.0/get-started/).
 
 ### Setup
 
-To work properly, this module needs a basic configuration, using the edcConfigurationProvider.
+To import the edc help module, add it to your module dependencies (`edcHelpModule`).
+The help module needs a basic configuration, injected with the edcConfigurationProvider.
 
 ```javascript
 
@@ -67,84 +75,123 @@ function EdcConfiguration(edcConfigurationProvider) {
         docPath: '/doc',
         pluginId: 'edchelp',
         icon: 'fa-question-circle-o',
-        // You can specify the options to set globally 
+        // You can specify the options to be set globally 
         options: {
-            appendTo: 'parent'
+            placement: 'top'
         }
     });
 }
 
 ```
-The edc-help component will then be available anywhere in your application
+
+### Usage
+
+The edc-help component will then be available in your application
+
 
 ```html
 
-<edc-help mainKey='myKey' subKey='mySubKey'></edc-help>
+<edc-help main-key="'my.key'" sub-key="'my.sub.key'"></edc-help>
 
 ```
 
-Configuration properties :
-| Property | Type | Description |
+## Inputs and options
+
+#### Mandatory inputs
+Mandatory inputs or the `EdcHelp` (see [HelpComponent](./projects/edc-popover-ng/src/lib/help.component.ts)):
+
+| Prop | Type | Description |
 |---|---|---|
-| pluginId | `string` | The identifier of the target plugin documentation export |
-| helpPath | `string` | The path to [edc-help-viewer](https://github.com/tech-advantage/edc-help-viewer) for opening the documentation. It needs to be the same as the **base href** parameter used by the viewer. See [here](https://github.com/tech-advantage/edc-help-viewer) for more information.|
-| docPath  | `string` | The path to exported documentation |
-| i18nPath | `string` | The path to translation json files |
-| icon  | `string` | The icon to use |
-| options | `Object` | Global options for the popovers (see below) |
+| mainKey | `string` | The main key of the contextual help |
+| subKey | `string` | The sub key of the contextual help |
 
-Global options (more to come):
 
-| Property | Type | Description | Default |
-|---|---|---|---|
-| placement | popper.js `Placement` | The popover placement | `bottom` |
-| customClass | `string` | class name that will be added to the main popover container | undefined |
-| appendTo | `parent` or `Element` | the element that will contain the popover | `body` |
+#### Optional inputs
+Optional inputs for the component:
 
-### Usage
+| 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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard. Will use documentation's default if no value is provided  | `undefined` |
+| options | [EdcPopoverOptions](./projects/edc-popover-ng/src/lib/config/edc-popover-options.ts) | Options for this popover - will overwrite global options | `undefined` |
 
-You just need to insert the edc-help component in your templates
+Available options [(EdcPopoverOptions)](./projects/edc-popover-ng/src/lib/config/edc-popover-options.ts):
 
-```html
+| Property | Type | Description | Default |
+|---|---|---|---|
+| icon | `PopoverIcon` | Icon settings, see [Icon](#Icon) | [PopoverIcon](./projects/edc-popover-ng/src/lib/config/popover-icon.ts) |
+| failBehavior | `FailBehavior` | Icon and popover behavior on error, see [Fail Behavior](#fail-behavior)  | [FailBehavior](./projects/edc-popover-ng/src/lib/config/fail-behavior.ts) |
+| 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](./projects/edc-popover-ng/src/lib/config/popover-icon.ts) contains the options for the icon.
 
-<edc-help mainKey='myKey' subKey='mySubKey'></edc-help>
+| Property | Type | Description | Default |
+|---|---|---|---|
+| class | `string` | Class name for the icon. [Font awesome icon classes](https://fontawesome.com/v4.7.0/cheatsheet/) 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.
 
-Mandatory inputs:
+#### 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](./projects/edc-popover-ng/src/lib/config/fail-behavior.ts) options to define their style and content.
 
-The `mainKey` and `subKey` inputs are necessary to identify the help content
+There are separate behaviors for the help icon, and the popover itself.
 
-| Prop | Type | Description |
+For the help icon when an error occurs, it adds the following css selector.
+
+| Behavior | Description | CSS selector |
 |---|---|---|
-| mainKey | `string` | The main key of the contextual help |
-| subKey | `string` | The sub key of the contextual help |
+| `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` |
 
-Optional inputs:
+Default values are in file [help.less](./projects/edc-popover-ng/src/lib/help.less)
 
-| Method | Return type | Description | Default value |
-|---|---|---|---|
-| pluginId | `string` | A custom pluginId | `undefined` (will use the global one) |
-| dark | `boolean` | true if dark mode enabled | `false` |
-| placement | `string` | Positions can be `auto` `top` `bottom` `right` `left`... (see full list below) | `bottom` |
-| lang | `string` | A language | `undefined` (keeps the language from the provider) |
-| customClass | `string` | A css class name for style customization | `undefined` |
-| appendTo | `parent` or `body` | Element that will receive the popover | `body` |
+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`.
 
 ## Customization
 
 ### CSS
 
 #### Global
 
-When dark-mode is enabled, the CSS class `on-dark` is applied to the help icon.
+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 :
+
+![CSS Classes](./CSSClasses.png)
+
 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, to change the background color
+For example, if you'd like to change the background color of the popover
 ```css
 .my-custom-class {
     background-color: lightgreen;
@@ -155,6 +202,41 @@ For example, to change the background color
 }
 ```
 
+## 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](https://github.com/tech-advantage/edc-popover-ng/src/lib/translate/language-codes.ts).
+
+##### JSON file structure
+
+Here is the en.json file used by default:
+
+```json
+{
+  "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": ""
+  }
+}
+```
+
 ## Tests
 
 ### Unit

diff --git a/dist/edc-popover-ng1.css b/dist/edc-popover-ng1.css
diff --git a/dist/edc-popover-ng1.js b/dist/edc-popover-ng1.js
diff --git a/package.json b/package.json
@@ -1,13 +1,13 @@
 {
   "name": "edc-popover-ng1",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "AngularJS Popover library for edc",
   "main": "dist/edc-popover-ng1.js",
   "scripts": {
     "build": "webpack --config ./webpack/webpack.prod.js",
     "start": "webpack --config ./webpack/webpack.dev.js",
     "test": "karma start",
-    "test-auto": "ng test edc-popover-ng"
+    "test-auto": "karma start --singleRun=false"
   },
   "keywords": [
     "edc",
@@ -17,48 +17,48 @@
   "license": "MIT",
   "dependencies": {
     "edc-client-js": "^3.1.3",
-    "edc-popover-js": "^1.0.0"
+    "edc-popover-utils": "^1.0.0"
   },
   "devDependencies": {
-    "@types/angular": "^1.7.2",
+    "@types/angular": "^1.7.3",
     "@types/angular-mocks": "^1.7.0",
-    "@types/core-js": "^2.5.3",
-    "@types/jasmine": "^3.5.11",
-    "@types/node": "^14.0.18",
-    "@types/webpack": "^4.41.20",
-    "@types/webpack-env": "^1.15.2",
-    "@typescript-eslint/eslint-plugin": "^3.6.0",
-    "@typescript-eslint/eslint-plugin-tslint": "^3.6.0",
-    "@typescript-eslint/parser": "^3.6.0",
+    "@types/core-js": "^2.5.4",
+    "@types/jasmine": "^3.5.14",
+    "@types/node": "^14.11.2",
+    "@types/webpack": "^4.41.22",
+    "@types/webpack-env": "^1.15.3",
+    "@typescript-eslint/eslint-plugin": "^4.2.0",
+    "@typescript-eslint/eslint-plugin-tslint": "^4.2.0",
+    "@typescript-eslint/parser": "^4.2.0",
     "angular": "^1.8.0",
     "angular-mocks": "^1.8.0",
     "clean-webpack-plugin": "^3.0.0",
     "core-js": "^3.6.5",
-    "css-loader": "^3.6.0",
-    "eslint": "^7.4.0",
+    "css-loader": "^4.3.0",
+    "eslint": "^7.10.0",
     "eslint-loader": "^4.0.2",
-    "file-loader": "^6.0.0",
-    "jasmine": "^3.5.0",
-    "karma": "^5.1.0",
+    "file-loader": "^6.1.0",
+    "jasmine": "^3.6.2",
+    "karma": "^5.2.3",
     "karma-chrome-launcher": "^3.1.0",
-    "karma-jasmine": "^3.3.1",
-    "karma-sourcemap-loader": "^0.3.7",
+    "karma-jasmine": "^4.0.1",
+    "karma-sourcemap-loader": "^0.3.8",
     "karma-spec-reporter": "^0.0.32",
     "karma-webpack": "^4.0.2",
-    "less": "^3.11.3",
-    "less-loader": "^6.2.0",
-    "mini-css-extract-plugin": "^0.9.0",
+    "less": "^3.12.2",
+    "less-loader": "^7.0.1",
+    "mini-css-extract-plugin": "^0.11.2",
     "node-sass": "^4.14.1",
-    "optimize-css-assets-webpack-plugin": "^5.0.3",
-    "sass-loader": "^9.0.1",
+    "optimize-css-assets-webpack-plugin": "^5.0.4",
+    "sass-loader": "^10.0.2",
     "style-loader": "^1.2.1",
-    "terser-webpack-plugin": "^3.0.6",
-    "ts-loader": "^8.0.1",
-    "tslint": "^6.1.2",
-    "typescript": "^3.9.6",
-    "webpack": "^4.43.0",
+    "terser-webpack-plugin": "^4.2.2",
+    "ts-loader": "^8.0.4",
+    "tslint": "^6.1.3",
+    "typescript": "^4.0.3",
+    "webpack": "^4.44.2",
     "webpack-cli": "^3.3.12",
-    "webpack-merge": "^5.0.8"
+    "webpack-merge": "^5.1.4"
   },
   "peerDependencies": {
     "angular": ">=1.5",

diff --git a/src/config/config.ts b/src/config/config.ts
diff --git a/src/config/edc-configuration.provider.ts b/src/config/edc-configuration.provider.ts
@@ -3,7 +3,7 @@ import { EdcPopoverConfiguration } from './edc-popover-configuration';
 export const EDC_CONFIGURATION_NAME = 'edcConfiguration';
 
 /**
- * Set the configuration for all the popovers in the host application
+ * Sets the configuration for all the popovers in the host application
  *
  * Needs to be provided by the host application when importing the edc help module
  */
@@ -12,7 +12,7 @@ export class EdcConfigurationProvider {
     config: EdcPopoverConfiguration;
 
     /**
-     * Return the current configuration, when required by angular for dependency injection
+     * Returns the current configuration, when required by angular for dependency injection
      */
     $get(): EdcPopoverConfiguration {
         // This will be injected when requiring the 'edcPopoverConfig' dependency