Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@farengeyt451
farengeyt451 committed Sep 21, 2020
1 parent dbb380a commit f193939
Show file tree
Hide file tree
Showing 7 changed files with 92 additions and 107 deletions.
178 changes: 82 additions & 96 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,22 @@

<div align="center">
<h1>Angular 8+ wrapper for Tippy.js</h1>

[![Build Status](https://travis-ci.org/farengeyt451/ngx-tippy-wrapper.svg?branch=master)](https://travis-ci.org/farengeyt451/ngx-tippy-wrapper)
[![codecov](https://codecov.io/gh/farengeyt451/ngx-tippy-wrapper/branch/master/graph/badge.svg)](https://codecov.io/gh/farengeyt451/ngx-tippy-wrapper)
![npm](https://img.shields.io/npm/dt/ngx-tippy-wrapper)
![GitHub](https://img.shields.io/github/license/farengeyt451/ngx-tippy-wrapper)
</div>

[![Build Status](https://travis-ci.org/farengeyt451/ngx-tippy-wrapper.svg?branch=master)](https://travis-ci.org/farengeyt451/ngx-tippy-wrapper)
[![codecov](https://codecov.io/gh/farengeyt451/ngx-tippy-wrapper/branch/master/graph/badge.svg)](https://codecov.io/gh/farengeyt451/ngx-tippy-wrapper)
![npm](https://img.shields.io/npm/dt/ngx-tippy-wrapper)
![GitHub](https://img.shields.io/github/license/farengeyt451/ngx-tippy-wrapper)

</div>

## Demo

[Example application](https://s8q4n.csb.app/)

[Code playground](https://codesandbox.io/s/ngx-tippy-wrapper-s8q4n)

[Run demo locally](./projects/demo/README.md)

## Installation

Install from npm:
Expand Down Expand Up @@ -46,7 +48,7 @@ Then in your base module:
})
```

Import base style file to your main style file:
Import `tippy.css` style file to your main style file:

```css
@import 'tippy.js/dist/tippy.css';
Expand All @@ -71,9 +73,7 @@ or angular.json:
Apply `ngxTippy` directive for element and pass content through `data-tippy-content` attribute:
```html
<button ngxTippy data-tippy-content="Tooltip content">
Element with tooltip
</button>
<button ngxTippy data-tippy-content="Tooltip content">Element with tooltip</button>
```
### Applying props
Expand All @@ -87,7 +87,6 @@ In template:
<button
ngxTippy
data-tippy-content="Tooltip content"
class="t-demo__btn"
[tippyProps]="{
arrow: false,
placement: 'bottom'
Expand All @@ -101,9 +100,7 @@ In template:
Or pass `props` from component:
```html
<span ngxTippy data-tippy-content="Tooltip content" [tippyProps]="tippyProps">
Element with tooltip
</span>
<span ngxTippy data-tippy-content="Tooltip content" [tippyProps]="tippyProps"> Element with tooltip </span>
```
---
Expand Down Expand Up @@ -138,31 +135,14 @@ export class DemoComponent implements OnInit {
## Applying content
#### You can pass content for tooltip through:
#### You can pass tooltip content through:
1. **`data` attribute**:
```html
<button ngxTippy data-tippy-content="Tooltip content">
Element with tooltip
</button>
<button ngxTippy data-tippy-content="Tooltip content">Element with tooltip</button>
```
---
```ts
...
import { NgxTippyProps } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit {
bindedContent: string = 'Binded tooltip content';
...
}
```
_Content binding_ works during component _initialization_, if new content should be set dynamic or reset again - use `setContent()` method
2. **`content` prop** :
```html
Expand All @@ -177,14 +157,10 @@ _Content binding_ works during component _initialization_, if new content should
</button>
```

3. **`setContent()` method** :

For this method `tippyName` prop should be setted
3. **`setContent()*` method** :

```html
<button ngxTippy tippyName="content">
Element with tooltip
</button>
<button ngxTippy tippyName="content">Element with tooltip</button>
```

---
Expand All @@ -211,12 +187,14 @@ export class DemoComponent implements OnInit, AfterViewInit {
}
```

\*_For this method `tippyName` should be defined_

\*_This method can be used for dynamic applying content at any time, not only in lifecycle hooks_

4. **`tippyProps`**:

```html
<button ngxTippy [tippyProps]="tippyProps">
Element with tooltip
</button>
<button ngxTippy [tippyProps]="tippyProps">Element with tooltip</button>
```

---
Expand Down Expand Up @@ -283,7 +261,7 @@ export class DemoComponent implements OnInit {
...
</div>

<!-- If passing element innerHTML -->
<!-- If passing element `innerHTML` -->
<div #tippyTemplate style="display: none;">
<h4>Caption</h4>
<p>Some content</p>
Expand All @@ -301,7 +279,7 @@ import { NgxTippyProps } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements AfterViewInit {
@ViewChild('tippyTemplate', { read: ElementRef, static: false }) tippyTemplate: ElementRef;
@ViewChild('tippyTemplate', { read: ElementRef, static: true }) tippyTemplate: ElementRef;
tippyContent: NgxTippyProps = { ... };

constructor(private ngxTippyService: NgxTippyService) {}
Expand All @@ -318,7 +296,7 @@ export class DemoComponent implements AfterViewInit {

// or

// Pass element innerHTML
// Pass element `innerHTML`
this.ngxTippyService.setContent('content', template.innerHTML);
}
...
Expand All @@ -327,8 +305,6 @@ export class DemoComponent implements AfterViewInit {

## Methods

_For accessing and control specific tippy instance you need pass `tippyName` prop_

Import and provide `NgxTippyService`:

```ts
Expand All @@ -342,6 +318,8 @@ export class DemoComponent implements OnInit {
}
```

_For accessing and control specific tippy instance `tippyName` should be defined_

Through service you can use all methods described [here](https://atomiks.github.io/tippyjs/v6/methods/) and some additional

### Implemented methods
Expand Down Expand Up @@ -381,31 +359,7 @@ Through service you can use all methods described [here](https://atomiks.github.
| showAll() | - | Show all tippies |
| hideAll() | `options?`: NgxHideAllOptions | Hide all tippies or hide all except a particular one, additional hide them with duration |

#### Available subscription to changes of tippy instances

It provides information in format:

```ts
{
name: string;
reason: InstanceChangeReason;
instance: NgxTippyInstance;
}

type InstanceChangeReason =
| 'setInstance'
| 'show'
| 'hide'
| 'hideWithInteractivity'
| 'disable'
| 'enable'
| 'setProps'
| 'setContent'
| 'setTriggerTarget'
| 'unmount'
| 'clearDelayTimeouts'
| 'destroy';
```
### Subscription for tippy instances change

```ts
...
Expand Down Expand Up @@ -435,6 +389,30 @@ export class DemoComponent implements OnInit, OnDestroy {
}
```

It provides information in format:

```ts
{
name: string;
reason: InstanceChangeReason;
instance: NgxTippyInstance;
}

type InstanceChangeReason =
| 'setInstance'
| 'show'
| 'hide'
| 'hideWithInteractivity'
| 'disable'
| 'enable'
| 'setProps'
| 'setContent'
| 'setTriggerTarget'
| 'unmount'
| 'clearDelayTimeouts'
| 'destroy';
```

## Grouped tooltips

If you want to give different tooltip content to many different elements, while only needing to initialize once with shared props use `ngx-tippy-group` component:
Expand All @@ -451,37 +429,34 @@ If you want to give different tooltip content to many different elements, while
```
<!-- prettier-ignore-end -->

_For each grouped tooltip you should pass `data-grouped` attribute_
_For each tooltip within component you should pass `data-grouped` attribute_

Also content can be binded and shared props overridden (see [customization](https://atomiks.github.io/tippyjs/v6/customization/)):
Also you can pass new content and props for every tooltip element, see [customization](https://atomiks.github.io/tippyjs/v6/customization/):

<!-- prettier-ignore-start -->
```html
<ngx-tippy-group [tippyProps]="tippyProps">

<ngx-tippy-group [tippyProps]="tippyPropsEx13">
<button
data-grouped
[attr.data-tippy-content]="bindedContent"
data-tippy-content="Tooltip content"
>
Element with tooltip
Group
</button>

<button
data-grouped
[attr.data-tippy-content]="bindedHTMLContent"
data-tippy-allowHTML="true"
data-tippy-content="Tooltip content"
>
Element with tooltip
Group
</button>

<button
data-grouped
data-tippy-content="Tooltip content"
data-tippy-arrow="false"
>
Element with tooltip
Group
</button>

</ngx-tippy-group>
```
<!-- prettier-ignore-end -->
Expand All @@ -503,7 +478,7 @@ export class DemoComponent implements OnInit {

## Multiple tooltips on a single element

For using multiple tooltips on a single element - nest elements with applied `ngxTippy` directive:
For multiple tooltips on a single element - use nest elements with applied `ngxTippy` directive:

<!-- prettier-ignore-start -->
```html
Expand All @@ -518,7 +493,6 @@ For using multiple tooltips on a single element - nest elements with applied `ng
[tippyProps]="{ ... }"
>
<button
class="t-demo__btn"
ngxTippy
data-tippy-content="Third tooltip content"
[tippyProps]="{ ... }"
Expand All @@ -532,52 +506,64 @@ For using multiple tooltips on a single element - nest elements with applied `ng

## Singleton

For [singleton](https://atomiks.github.io/tippyjs/v6/addons/) using - put in tooltips inside `ngx-tippy-singleton` component:
For [singleton](https://atomiks.github.io/tippyjs/v6/addons/) - provide tooltips elements within `ngx-tippy-singleton` component:

<!-- prettier-ignore-start -->
```html
<ngx-tippy-singleton [tippyProps]="{ ... }">

<button
data-singleton
data-tippy-content="First tooltip content"
>
Element with tooltip
Singleton
</button>

<button
data-singleton
data-tippy-content="First tooltip content"
data-tippy-content="Second tooltip content"
>
Element with tooltip
Singleton
</button>

<button
data-singleton
data-tippy-content="Third tooltip content"
>
Singleton
</button>
</ngx-tippy-singleton>
```
<!-- prettier-ignore-end-->

To overrides general `tippyProps` by the individual tippy `props`:
_For each tooltip you should pass `data-singleton` attribute_

**To overrides general `tippyProps` by the individual tippy `props`:**

<!-- prettier-ignore-start -->
```html
<ngx-tippy-singleton [tippyProps]="{ ... }">

<ngx-tippy-singleton [tippyProps]="tippyProps">
<button
data-singleton
data-tippy-content="First tooltip content"
data-tippy-placement="bottom"
>
Element with tooltip
Singleton
</button>

<button
data-singleton
data-tippy-content="First tooltip content"
data-tippy-content="Second tooltip content"
data-tippy-arrow="false"
>
Element with tooltip
Singleton
</button>

<button
data-singleton
data-tippy-content="Third tooltip content"
>
Singleton
</button>
</ngx-tippy-singleton>
```
<!-- prettier-ignore-end -->
Expand Down
5 changes: 3 additions & 2 deletions projects/demo/package-lock.json
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit f193939

Please sign in to comment.