Skip to content

Commit

Permalink
docs: README improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
Federico Zivolo committed Aug 6, 2018
1 parent a1b77f0 commit a65a6a1
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 60 deletions.
102 changes: 47 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
<p align="center">
<img src="https://badge-size.now.sh/https://unpkg.com/popper.js/dist/popper.min.js?compression=brotli" alt="Stable Release Size"/>
<img src="https://badge-size.now.sh/https://unpkg.com/popper.js/dist/popper.min.js?compression=gzip" alt="Stable Release Size"/>
<a href="https://www.bithound.io/github/FezVrasta/popper.js"><img src="https://www.bithound.io/github/FezVrasta/popper.js/badges/score.svg" alt="bitHound Overall Score"></a>
<a href="https://codeclimate.com/github/FezVrasta/popper.js/coverage"><img src="https://codeclimate.com/github/FezVrasta/popper.js/badges/coverage.svg" alt="Istanbul Code Coverage"/></a>
<a href="https://www.npmjs.com/browse/depended/popper.js"><img src="https://badgen.net/npm/dependents/popper.js" alt="Dependents packages" /></a>
<a href="https://spectrum.chat/popper-js" target="_blank"><img src="https://img.shields.io/badge/chat-on_spectrum-6833F9.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyBpZD0iTGl2ZWxsb18xIiBkYXRhLW5hbWU9IkxpdmVsbG8gMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgMTAgOCI%2BPGRlZnM%2BPHN0eWxlPi5jbHMtMXtmaWxsOiNmZmY7fTwvc3R5bGU%2BPC9kZWZzPjx0aXRsZT5zcGVjdHJ1bTwvdGl0bGU%2BPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNNSwwQy40MiwwLDAsLjYzLDAsMy4zNGMwLDEuODQuMTksMi43MiwxLjc0LDMuMWgwVjcuNThhLjQ0LjQ0LDAsMCwwLC42OC4zNUw0LjM1LDYuNjlINWM0LjU4LDAsNS0uNjMsNS0zLjM1UzkuNTgsMCw1LDBaTTIuODMsNC4xOGEuNjMuNjMsMCwxLDEsLjY1LS42M0EuNjQuNjQsMCwwLDEsMi44Myw0LjE4Wk01LDQuMThhLjYzLjYzLDAsMSwxLC42NS0uNjNBLjY0LjY0LDAsMCwxLDUsNC4xOFptMi4xNywwYS42My42MywwLDEsMSwuNjUtLjYzQS42NC42NCwwLDAsMSw3LjE3LDQuMThaIi8%2BPC9zdmc%2B" alt="Get support or discuss"/></a>
<br />
<a href="https://travis-ci.org/FezVrasta/popper.js/branches" target="_blank"><img src="https://travis-ci.org/FezVrasta/popper.js.svg?branch=master" alt="Build Status"/></a>
Expand All @@ -26,12 +26,11 @@
A popper is an element on the screen which "pops out" from the natural flow of your application.
Common examples of poppers are tooltips, popovers, and drop-downs.


## So, yet another tooltip library?

Well, basically, **no**.
Popper.js is a **positioning engine**, its purpose is to calculate the position of an element
to make it possible to position it near a given reference element.
to make it possible to position it near a given reference element.

The engine is completely modular and most of its features are implemented as **modifiers**
(similar to middlewares or plugins).
Expand All @@ -56,7 +55,6 @@ Visit our [project page](https://fezvrasta.github.io/popper.js) to see a lot of

Find [the documentation here](docs/_includes/popper-documentation.md).


### Tooltip.js

Since lots of users just need a simple way to integrate powerful tooltips in their projects,
Expand All @@ -68,28 +66,28 @@ The tooltips generated by Tooltip.js are accessible thanks to the `aria` tags.

Find [the documentation here](docs/_includes/tooltip-documentation.md).


## Installation

Popper.js is available on the following package managers and CDNs:

| Source | |
|:-----------------|:---------------------------------------------------------------------------------------------------------------|
| npm | `npm install popper.js --save` |
| yarn | `yarn add popper.js` |
| NuGet | `PM> Install-Package popper.js` |
| Bower | `bower install popper.js --save` |
| unpkg | [`https://unpkg.com/popper.js`](https://unpkg.com/popper.js) |
| unpkg, minified | [`https://unpkg.com/popper.js/dist/umd/popper.min.js`](https://unpkg.com/popper.js/dist/umd/popper.min.js) |
| Source | |
| :-------------- | :--------------------------------------------------------------------------------------------------------- |
| npm | `npm install popper.js --save` |
| yarn | `yarn add popper.js` |
| NuGet | `PM> Install-Package popper.js` |
| Bower | `bower install popper.js --save` |
| unpkg | [`https://unpkg.com/popper.js`](https://unpkg.com/popper.js) |
| unpkg, minified | [`https://unpkg.com/popper.js/dist/umd/popper.min.js`](https://unpkg.com/popper.js/dist/umd/popper.min.js) |

Tooltip.js as well:

| Source | |
|:-----------------|:---------------------------------------------------------------------------------------------------------------|
| npm | `npm install tooltip.js --save` |
| yarn | `yarn add tooltip.js` |
| Bower* | `bower install tooltip.js=https://unpkg.com/tooltip.js --save` |
| unpkg | [`https://unpkg.com/tooltip.js`](https://unpkg.com/tooltip.js) |
| unpkg, minified | [`https://unpkg.com/tooltip.js/dist/umd/tooltip.min.js`](https://unpkg.com/tooltip.js/dist/umd/tooltip.min.js) |
| Source | |
| :-------------- | :------------------------------------------------------------------------------------------------------------- |
| npm | `npm install tooltip.js --save` |
| yarn | `yarn add tooltip.js` |
| Bower\* | `bower install tooltip.js=https://unpkg.com/tooltip.js --save` |
| unpkg | [`https://unpkg.com/tooltip.js`](https://unpkg.com/tooltip.js) |
| unpkg, minified | [`https://unpkg.com/tooltip.js/dist/umd/tooltip.min.js`](https://unpkg.com/tooltip.js/dist/umd/tooltip.min.js) |

\*: Bower isn't officially supported, it can be used to install Tooltip.js only trough the unpkg.com CDN. This method has the limitation of not being able to define a specific version of the library. Bower and Popper.js suggests to use npm or Yarn for your projects.
For more info, [read the related issue](https://github.com/FezVrasta/popper.js/issues/390).
Expand All @@ -113,13 +111,9 @@ Given an existing popper DOM node, ask Popper.js to position it near its button
```js
var reference = document.querySelector('.my-button');
var popper = document.querySelector('.my-popper');
var anotherPopper = new Popper(
reference,
popper,
{
// popper options here
}
);
var anotherPopper = new Popper(reference, popper, {
// popper options here
});
```

### Callbacks
Expand All @@ -131,32 +125,31 @@ the popper has been initialized. The `onUpdate` one is called on any subsequent
const reference = document.querySelector('.my-button');
const popper = document.querySelector('.my-popper');
new Popper(reference, popper, {
onCreate: (data) => {
// data is an object containing all the informations computed
// by Popper.js and used to style the popper and its arrow
// The complete description is available in Popper.js documentation
},
onUpdate: (data) => {
// same as `onCreate` but called on subsequent updates
}
onCreate: data => {
// data is an object containing all the informations computed
// by Popper.js and used to style the popper and its arrow
// The complete description is available in Popper.js documentation
},
onUpdate: data => {
// same as `onCreate` but called on subsequent updates
},
});
```

### Writing your own modifiers

Popper.js is based on a "plugin-like" architecture, most of its features are fully encapsulated "modifiers".
A modifier is a function that is called each time Popper.js needs to compute the position of the popper. For this reason, modifiers should be very performant to avoid bottlenecks.
A modifier is a function that is called each time Popper.js needs to compute the position of the popper. For this reason, modifiers should be very performant to avoid bottlenecks.

To learn how to create a modifier, [read the modifiers documentation](docs/_includes/popper-documentation.md#modifiers--object)


### React, Vue.js, Angular, AngularJS, Ember.js (etc...) integration

Integrating 3rd party libraries in React or other libraries can be a pain because
they usually alter the DOM and drive the libraries crazy.
Popper.js limits all its DOM modifications inside the `applyStyle` modifier,
you can simply disable it and manually apply the popper coordinates using
your library of choice.
your library of choice.

For a comprehensive list of libraries that let you use Popper.js into existing
frameworks, visit the [MENTIONS](MENTIONS.md) page.
Expand All @@ -166,30 +159,28 @@ integrate Popper.js by yourself!

```js
function applyReactStyle(data) {
// export data in your framework and use its content to apply the style to your popper
};
// export data in your framework and use its content to apply the style to your popper
}

const reference = document.querySelector('.my-button');
const popper = document.querySelector('.my-popper');
new Popper(reference, popper, {
modifiers: {
applyStyle: { enabled: false },
applyReactStyle: {
enabled: true,
fn: applyReactStyle,
order: 900,
},
modifiers: {
applyStyle: { enabled: false },
applyReactStyle: {
enabled: true,
fn: applyReactStyle,
order: 900,
},
},
});

```

### How to use Popper.js in Jest

It is recommended that users mock Popper.js for use in Jest tests due to some limitations of JSDOM.


The simplest way to mock Popper.js is to place the following code in `__mocks__/popper.js.js` adjacent to your `node_modules` directory. Jest will pick it up automatically.
The simplest way to mock Popper.js is to place the following code in `__mocks__/popper.js.js` adjacent to your `node_modules` directory. Jest will pick it up automatically.

```js
import PopperJs from 'popper.js';
Expand All @@ -200,7 +191,7 @@ export default class Popper {
constructor() {
return {
destroy: () => {},
scheduleUpdate: () => {}
scheduleUpdate: () => {},
};
}
}
Expand All @@ -218,7 +209,7 @@ jest.mock('popper.js', () => {
constructor() {
return {
destroy: () => {},
scheduleUpdate: () => {}
scheduleUpdate: () => {},
};
}
};
Expand All @@ -228,7 +219,7 @@ jest.mock('popper.js', () => {
### Migration from Popper.js v0

Since the API changed, we prepared some migration instructions to make it easy to upgrade to
Popper.js v1.
Popper.js v1.

https://github.com/FezVrasta/popper.js/issues/62

Expand All @@ -244,12 +235,12 @@ This means that it will not cause any [jank](https://www.chromium.org/developers
### Libraries using Popper.js

The aim of Popper.js is to provide a stable and powerful positioning engine ready to
be used in 3rd party libraries.
be used in 3rd party libraries.

Visit the [MENTIONS](MENTIONS.md) page for an updated list of projects.


### Credits

I want to thank some friends and projects for the work they did:

- [@AndreaScn](https://github.com/AndreaScn) for his work on the GitHub Page and the manual testing he did during the development;
Expand All @@ -260,4 +251,5 @@ I want to thank some friends and projects for the work they did:
- **you** for the star you'll give to this project and for being so awesome to give this project a try 🙂

### Copyright and license

Code and documentation copyright 2016 **Federico Zivolo**. Code released under the [MIT license](https://github.com/FezVrasta/popper.js/blob/master/LICENSE.md). Docs released under Creative Commons.
11 changes: 6 additions & 5 deletions packages/popper/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,14 @@
</p>

<p align="center">
<a href="https://travis-ci.org/FezVrasta/popper.js/branches" target="_blank"><img src="https://travis-ci.org/FezVrasta/popper.js.svg?branch=master" alt="Build Status"/></a>
<img src="https://img.badgesize.io/https://unpkg.com/popper.js/dist/popper.min.js?compression=gzip" alt="Stable Release Size"/>
<a href="https://www.bithound.io/github/FezVrasta/popper.js"><img src="https://www.bithound.io/github/FezVrasta/popper.js/badges/score.svg" alt="bitHound Overall Score"></a>
<img src="https://badge-size.now.sh/https://unpkg.com/popper.js/dist/popper.min.js?compression=brotli" alt="Stable Release Size"/>
<img src="https://badge-size.now.sh/https://unpkg.com/popper.js/dist/popper.min.js?compression=gzip" alt="Stable Release Size"/>
<a href="https://codeclimate.com/github/FezVrasta/popper.js/coverage"><img src="https://codeclimate.com/github/FezVrasta/popper.js/badges/coverage.svg" alt="Istanbul Code Coverage"/></a>
<a href="https://gitter.im/FezVrasta/popper.js" target="_blank"><img src="https://img.shields.io/gitter/room/nwjs/nw.js.svg" alt="Get support or discuss"/></a>
<a href="https://www.npmjs.com/browse/depended/popper.js"><img src="https://badgen.net/npm/dependents/popper.js" alt="Dependents packages" /></a>
<a href="https://spectrum.chat/popper-js" target="_blank"><img src="https://img.shields.io/badge/chat-on_spectrum-6833F9.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyBpZD0iTGl2ZWxsb18xIiBkYXRhLW5hbWU9IkxpdmVsbG8gMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgMTAgOCI%2BPGRlZnM%2BPHN0eWxlPi5jbHMtMXtmaWxsOiNmZmY7fTwvc3R5bGU%2BPC9kZWZzPjx0aXRsZT5zcGVjdHJ1bTwvdGl0bGU%2BPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNNSwwQy40MiwwLDAsLjYzLDAsMy4zNGMwLDEuODQuMTksMi43MiwxLjc0LDMuMWgwVjcuNThhLjQ0LjQ0LDAsMCwwLC42OC4zNUw0LjM1LDYuNjlINWM0LjU4LDAsNS0uNjMsNS0zLjM1UzkuNTgsMCw1LDBaTTIuODMsNC4xOGEuNjMuNjMsMCwxLDEsLjY1LS42M0EuNjQuNjQsMCwwLDEsMi44Myw0LjE4Wk01LDQuMThhLjYzLjYzLDAsMSwxLC42NS0uNjNBLjY0LjY0LDAsMCwxLDUsNC4xOFptMi4xNywwYS42My42MywwLDEsMSwuNjUtLjYzQS42NC42NCwwLDAsMSw3LjE3LDQuMThaIi8%2BPC9zdmc%2B" alt="Get support or discuss"/></a>
<br />
<a href="https://saucelabs.com/u/popperjs" target="_blank"><img src="https://badges.herokuapp.com/browsers?labels=none&googlechrome=latest&firefox=latest&microsoftedge=latest&iexplore=11,10&safari=latest&iphone=latest" alt="SauceLabs Reports"/></a>
<a href="https://travis-ci.org/FezVrasta/popper.js/branches" target="_blank"><img src="https://travis-ci.org/FezVrasta/popper.js.svg?branch=master" alt="Build Status"/></a>
<a href="https://saucelabs.com/u/popperjs" target="_blank"><img src="https://badges.herokuapp.com/browsers?labels=none&googlechrome=latest&firefox=latest&microsoftedge=latest&iexplore=11,10&safari=latest" alt="SauceLabs Reports"/></a>
</p>

<img src="https://raw.githubusercontent.com/FezVrasta/popper.js/master/popperjs.png" align="right" width=250 />
Expand Down

0 comments on commit a65a6a1

Please sign in to comment.