npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

edc-popover-ng1

v2.1.0

Published

AngularJS Popover library for edc

Downloads

7

Readme

edc-popover-ng1

Build Status npm version

AngularJS 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.

Dependencies

The required dependencies are:

How to use

Import

You can import this module with npm by running:

npm install edc-popover-ng1 --save

Or with yarn:

yarn add edc-popover-ng1

import the css file in your main style file (e.g. style.less) :

@import '~edc-popover-ng1/dist/edc-popover-ng1.css';

You need to download font-awesome or install it as a dependency

npm install font-awesome --save

Then import the style.

<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

$fa-font-path: '~font-awesome/fonts/';
@import '~font-awesome/scss/font-awesome';

More info here.

Setup

To import the edc help module, add it to your module dependencies (edcHelpModule). The help module needs a basic configuration, injected with the edcConfigurationProvider.


angular.module('myApp', [
  'edcHelpModule'
]).config(EdcConfiguration);

// Where EdcConfiguration is a function to retrieve the edc configuration provider
function EdcConfiguration(edcConfigurationProvider) {
    // A setter is available to save your configuration, for example:
    edcConfigurationProvider.set({
        helpPath: '/help',
        docPath: '/doc',
        pluginId: 'edchelp',
        icon: 'fa-question-circle-o',
        // You can specify the options to be set globally 
        options: {
            placement: 'top'
        }
    });
}

Usage

The edc-help component will then be available in your application


<edc-help main-key="'my.key'" sub-key="'my.sub.key'"></edc-help>

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 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 edc-on-dark is applied to the help icon.

Popover

You can customize the popover with CSS classes as described below :

CSS Classes

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": ""
  }
}

Tests

Unit

You can test the project by running:

npm run test

or

yarn test