first
This commit is contained in:
shim
206
plugins/pulltorefresh/README.md
Normal file
206
plugins/pulltorefresh/README.md
Normal file
@@ -0,0 +1,206 @@
|
||||
|
||||
|
||||
[](https://travis-ci.org/BoxFactura/pulltorefresh.js)
|
||||
[](http://badge.fury.io/js/pulltorefreshjs)
|
||||
[](https://cdnjs.com/libraries/pulltorefreshjs)
|
||||
|
||||
[**PulltoRefresh.js**](http://www.boxfactura.com/pulltorefresh.js/) • [Demos](http://www.boxfactura.com/pulltorefresh.js/demos/basic.html)
|
||||
|
||||
A small, but powerful Javascript library crafted to power your webapp's pull to refresh feature. No markup needed, highly customizable and dependency-free!
|
||||
|
||||
---
|
||||
|
||||
## Donations
|
||||
|
||||
If you found this project helpful, please consider a donation.
|
||||
|
||||
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WYS5CSZWWLNN4)
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
Download PulltoRefresh either from the [NPM Registry](https://www.npmjs.com/package/pulltorefreshjs), [CDNJS](https://cdnjs.com/libraries/pulltorefreshjs) or [UNPKG](https://unpkg.com/pulltorefreshjs):
|
||||
|
||||
```bash
|
||||
$ npm install pulltorefreshjs --save-dev
|
||||
$ wget -O pulltorefresh.js https://unpkg.com/pulltorefreshjs
|
||||
```
|
||||
|
||||
Include the JS file in your webapp and initialize it:
|
||||
|
||||
```js
|
||||
const ptr = PullToRefresh.init({
|
||||
mainElement: 'body',
|
||||
onRefresh() {
|
||||
window.location.reload();
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
Bundlers can consume `pulltorefreshjs` as CommonJS and ES6-modules syntax:
|
||||
|
||||
```js
|
||||
import PullToRefresh from 'pulltorefreshjs';
|
||||
// or
|
||||
const PullToRefresh = require('pulltorefreshjs');
|
||||
```
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
- **`init(options)`**
|
||||
Will return a unique ptr-instance with a `destroy()` method.
|
||||
- **`destroyAll()`**
|
||||
Stop and remove all registered ptr-instances.
|
||||
- **`setPassiveMode(isPassive)`**
|
||||
Enable or disable passive mode for event handlers (new instances only).
|
||||
|
||||
## Options
|
||||
|
||||
- **`distThreshold`** (integer)
|
||||
Minimum distance required to trigger the refresh.
|
||||
<br />— Defaults to `60`
|
||||
- **`distMax`** (integer)
|
||||
Maximum distance possible for the element.
|
||||
<br />— Defaults to `80`
|
||||
- **`distReload`** (integer)
|
||||
After the `distThreshold` is reached and released, the element will have this height.
|
||||
<br />— Defaults to `50`
|
||||
- **`distIgnore`** (integer)
|
||||
After which distance should we start pulling?
|
||||
<br />— Defaults to `0`
|
||||
- **`mainElement`** (string)
|
||||
Before which element the pull to refresh elements will be?
|
||||
<br />— Defaults to `body`
|
||||
- **`triggerElement`** (string)
|
||||
Which element should trigger the pull to refresh?
|
||||
<br />— Defaults to `body`
|
||||
- **`ptrElement`** (string)
|
||||
Which class will the main element have?
|
||||
<br />— Defaults to `.ptr`
|
||||
- **`classPrefix`** (string)
|
||||
Which class prefix for the elements?
|
||||
<br />— Defaults to `ptr--`
|
||||
- **`cssProp`** (string)
|
||||
Which property will be usedto calculate the element's proportions?
|
||||
<br />— Defaults to `min-height`
|
||||
- **`iconArrow`** (string)
|
||||
The icon for both `instructionsPullToRefresh` and `instructionsReleaseToRefresh`
|
||||
<br />— Defaults to `⇣`
|
||||
- **`iconRefreshing`** (string)
|
||||
The icon when the refresh is in progress.
|
||||
<br />— Defaults to `…`
|
||||
- **`instructionsPullToRefresh`** (string)
|
||||
The initial instructions string.
|
||||
<br />— Defaults to `Pull down to refresh`
|
||||
- **`instructionsReleaseToRefresh`** (string)
|
||||
The instructions string when the `distThreshold` has been reached.
|
||||
<br />— Defaults to `Release to refresh`
|
||||
- **`instructionsRefreshing`** (string)
|
||||
The refreshing text.
|
||||
<br />— Defaults to `Refreshing`
|
||||
- **`refreshTimeout`** (integer)
|
||||
The delay, in milliseconds before the `onRefresh` is triggered.
|
||||
<br />— Defaults to `500`
|
||||
- **`getMarkup`** (function)
|
||||
It returns the default HTML for the widget, `__PREFIX__` is replaced.
|
||||
<br />— See [src/lib/markup.js](src/lib/markup.js)
|
||||
- **`getStyles`** (function)
|
||||
It returns the default CSS for the widget, `__PREFIX__` is replaced.
|
||||
<br />— See [src/lib/styles.js](src/lib/styles.js)
|
||||
- **`onInit`** (function)
|
||||
The initialize function.
|
||||
- **`onRefresh`** (function)
|
||||
What will the pull to refresh trigger? You can return a promise.
|
||||
<br />— Defaults to `window.location.reload()`
|
||||
- **`resistanceFunction`** (function)
|
||||
The resistance function, accepts one parameter, must return a number, capping at 1.
|
||||
<br />— Defaults to `t => Math.min(1, t / 2.5)`
|
||||
- **`shouldPullToRefresh`** (function)
|
||||
Which condition should be met for pullToRefresh to trigger?
|
||||
<br />— Defaults to `!window.scrollY` • Please note that this default is useful whenever you're setting mainElement as the body of the document, if you need it in another element with overflow, use `!this.mainElement.scrollTop`. Refer to the [multiple instances demo](https://www.boxfactura.com/pulltorefresh.js/demos/multiple.html) for reference.
|
||||
|
||||
## Use with React
|
||||
|
||||
With [ReactDOMServer](https://reactjs.org/docs/react-dom-server.html) and `renderToString()` you can use components as
|
||||
icons instead of just strings.
|
||||
In this example we also use [Font Awesome](https://fontawesome.com/how-to-use/on-the-web/using-with/react) to get nice icons with animation, but you can
|
||||
use any React component you like.
|
||||
|
||||
[Demo on codesandbox.io](https://codesandbox.io/s/21o9z8rrzy)
|
||||
|
||||
```jsx harmony
|
||||
|
||||
import React, { Component } from 'react';
|
||||
import ReactDOMServer from 'react-dom/server';
|
||||
import PullToRefresh from 'pulltorefreshjs';
|
||||
import { faSyncAlt} from '@fortawesome/free-solid-svg-icons';
|
||||
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
|
||||
|
||||
class App extends Component
|
||||
{
|
||||
componentDidMount()
|
||||
{
|
||||
PullToRefresh.init({
|
||||
mainElement: 'body',
|
||||
onRefresh() {
|
||||
window.location.reload();
|
||||
},
|
||||
iconArrow: ReactDOMServer.renderToString(
|
||||
<FontAwesomeIcon icon={faSyncAlt} />
|
||||
),
|
||||
iconRefreshing: ReactDOMServer.renderToString(
|
||||
<FontAwesomeIcon icon={faSyncAlt} spin={true} />
|
||||
),
|
||||
});
|
||||
}
|
||||
|
||||
componentWillUnmount()
|
||||
{
|
||||
// Don't forget to destroy all instances on unmout
|
||||
// or you will get some glitches.
|
||||
PullToRefresh.destroyAll();
|
||||
}
|
||||
|
||||
render()
|
||||
{
|
||||
return (
|
||||
<div>
|
||||
<h1>App</h1>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export default App;
|
||||
```
|
||||
|
||||
## Contribute
|
||||
|
||||
To quickly start the development workflow:
|
||||
|
||||
1. Install NodeJS ([NVM](https://github.com/creationix/nvm/blob/master/nvm.sh))
|
||||
2. Run `nvm use 10 && npm install`
|
||||
3. Then `npm run dev`
|
||||
|
||||
> This will watch and compile the bundle for browser usage.
|
||||
|
||||
E2E tests are executed with Testcafé.
|
||||
|
||||
- Run `npm test` to use standard Chrome
|
||||
- Run `npm pretest && npm run test:ci` to run Chrome in headless mode
|
||||
|
||||
Advanced debug can be achieved with `testcafe-live`, e.g.
|
||||
|
||||
```bash
|
||||
$ npm test --live chrome tests/e2e/cases --debug-on-fail
|
||||
```
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [ ] More events: `onPullStart`, `onPullDown(direction, willRefresh)`, `onRelease(willRefresh)`
|
||||
- [ ] Fully customizable CSS
|
||||
- [ ] Gallery of use cases
|
||||
- [ ] Advanced demos
|
||||
- [x] Tests
|
||||
- [x] Minified releases
|
||||
Reference in New Issue
Block a user