Skip to content

Commit 4b4ed89

Browse files
CodeByZachCodeByZach
committed
Merge branch 'master' into 502
# Conflicts: # docs/intro.md
2 parents 57270d6 + 4d6ed2b commit 4b4ed89

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+1314
-3228
lines changed

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +0,0 @@
1-
node_modules

‎.hsdoc‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎Gruntfile.coffee‎

Lines changed: 0 additions & 68 deletions
This file was deleted.

‎LICENSE‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,3 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
55
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
66

77
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
8-

‎README.md‎

Lines changed: 265 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,281 @@
1-
Disclaimer, We no longer use this library internally and are focusing our efforts on open sourcing and maintaining projects that we do use and can meaningfully contribute to. Sorry for any frustrations with this project (we're happy to link to any fork that has an excited, commited maintainer).
2-
3-
pace
1+
PACE
42
====
3+
[![Latest Release](https://img.shields.io/github/tag/CodeByZach/pace.svg?label=version)](https://github.com/CodeByZach/pace/releases)
54

65
An automatic web page progress bar.
76

8-
Include [pace.js](https://raw.github.com/HubSpot/pace/v1.0.2/pace.min.js) and a [theme](http://github.hubspot.com/pace/docs/welcome/) of your choice to your page and you are done!
7+
### [Demo](https://codebyzach.github.io/pace/)
8+
### [Documentation](https://codebyzach.github.io/pace/docs/)
99

10-
We also have a [Wordpress Plugin](https://wordpress.org/plugins/pace).
10+
Include [pace.js](https://raw.github.com/CodeByZach/pace/master/pace.min.js) and the
11+
[theme](https://codebyzach.github.io/pace/) css of your choice on your page
12+
(as early as is possible), and you're done!
1113

12-
Pace will automatically monitor your Ajax requests, event loop lag, document ready state and elements on your page to decide on the progress.
14+
Pace will automatically monitor your ajax requests, event loop lag, document
15+
ready state, and elements on your page to decide the progress. On ajax navigation
16+
it will begin again!
1317

1418
If you use AMD or Browserify, require pace.js and call `pace.start()` as early in the loading process as is possible.
1519

16-
### [Demo](http://github.hubspot.com/pace/docs/welcome/)
17-
18-
### [Documentation](http://github.hubspot.com/pace/)
19-
20-
### Example
20+
Example
21+
-------
2122

2223
```html
2324
<head>
2425
<script src="/pace/pace.js"></script>
2526
<link href="/pace/themes/pace-theme-barber-shop.css" rel="stylesheet" />
2627
</head>
2728
```
29+
30+
Configuration
31+
-------------
32+
33+
Pace is fully automatic, no configuration is necessary to get started.
34+
35+
If you would like to make some tweaks, here's how:
36+
37+
You can set `window.paceOptions` before bringing in the file:
38+
39+
```javascript
40+
paceOptions = {
41+
// Disable the 'elements' source
42+
elements: false,
43+
44+
// Only show the progress on regular and ajax-y page navigation,
45+
// not every request
46+
restartOnRequestAfter: false
47+
}
48+
```
49+
50+
You can also put options on the script tag:
51+
52+
```html
53+
<script data-pace-options='{ "ajax": false }' src='pace.js'></script>
54+
```
55+
56+
If you're using AMD or Browserify, you can pass your options to `start`:
57+
58+
```javascript
59+
define(['pace'], function(pace){
60+
pace.start({
61+
document: false
62+
});
63+
});
64+
```
65+
66+
Themes
67+
------
68+
69+
Pace includes a bunch of [themes](https://codebyzach.github.io/pace/)
70+
to get you started. Just include the appropriate css file. Send us a PR with
71+
any interesting themes you create.
72+
73+
If you have minor styling changes and don't want to extend theme css, you can add custom class names to
74+
the progress bar using the "className" option:
75+
76+
```javascript
77+
paceOptions = {
78+
className: 'my-custom-class'
79+
}
80+
```
81+
82+
Collectors
83+
----------
84+
85+
Collectors are the bits of code which gather progress information. Pace includes four default collectors:
86+
87+
- Ajax
88+
89+
Monitors all ajax requests on the page
90+
91+
- Elements
92+
93+
Checks for the existance of specific elements on the page
94+
95+
- Document
96+
97+
Checks the document readyState
98+
99+
- Event Lag
100+
101+
Checks for event loop lag signaling that javascript is being executed
102+
103+
They can each be configured or disabled through configuration options of the same name.
104+
105+
```javascript
106+
paceOptions = {
107+
ajax: false, // disabled
108+
document: false, // disabled
109+
eventLag: false, // disabled
110+
elements: {
111+
selectors: ['.my-page']
112+
}
113+
};
114+
```
115+
116+
Add your own classes to `paceOptions.extraSources` to add more sources. Each source should either
117+
have a `.progress` property, or a `.elements` property which is a list of objects with
118+
`.progress` properties. Pace will automatically handle all scaling to make the progress
119+
changes look smooth to the user.
120+
121+
Elements
122+
--------
123+
124+
Elements being rendered to the screen is one way for us to decide that the page has been
125+
rendered. If you would like to use that source of information (not required at all),
126+
specify one or more selectors. You can comma separate the selectors to propertly handle
127+
error states, where the progress bar should disappear, but the element we are looking for
128+
may never appear:
129+
130+
```javascript
131+
paceOptions = {
132+
elements: {
133+
selectors: ['.timeline,.timeline-error', '.user-profile,.profile-error']
134+
}
135+
}
136+
```
137+
138+
Pace will consider the elements test successful when each selector matches something. For
139+
this example, when either `.timeline` or `.timeline-error` exist, and either `.user-profile`
140+
or `.profile-error` exist.
141+
142+
Restart Rules
143+
-------------
144+
145+
Most users want the progress bar to automatically restart when a pushState event occurs
146+
(generally means ajax navigation is occuring). You can disable this:
147+
148+
```javascript
149+
paceOptions = {
150+
restartOnPushState: false
151+
}
152+
```
153+
154+
You can also have pace restart on every ajax request which lasts longer than x ms. You'll want to
155+
disable this if you make ajax requests the user doesn't need to know about, like precaching:
156+
157+
```javascript
158+
paceOptions = {
159+
restartOnRequestAfter: false
160+
}
161+
```
162+
163+
You can always trigger a restart manually by calling `Pace.restart()`
164+
165+
See [the source](https://github.com/CodeByZach/pace/blob/master/pace.js) for a full list of all options.
166+
167+
API
168+
---
169+
170+
Pace exposes the following methods:
171+
172+
- `Pace.start`: Show the progress bar and start updating. Called automatically if you don't use AMD or CommonJS.
173+
174+
- `Pace.restart`: Show the progress bar if it's hidden and start reporting the progress from scratch. Called automatically
175+
whenever `pushState` or `replaceState` is called by default.
176+
177+
- `Pace.stop`: Hide the progress bar and stop updating it.
178+
179+
- `Pace.track`: Explicitly track one or more requests, see Tracking below
180+
181+
- `Pace.ignore`: Explicitly ignore one or more requests, see Tracking below
182+
183+
Events
184+
------
185+
186+
Pace fires the following events:
187+
188+
- `start`: When pace is initially started, or as a part of a restart
189+
- `stop`: When pace is manually stopped, or as a part of a restart
190+
- `restart`: When pace is restarted (manually, or by a new AJAX request)
191+
- `done`: When pace is finished
192+
- `hide`: When the pace is hidden (can be later than `done`, based on `ghostTime` and `minTime`)
193+
194+
You can bind onto events using the `on`, `off` and `once` methods:
195+
196+
- `Pace.on(event, handler, [context])`: Call `handler` (optionally with context) when `event` is triggered
197+
- `Pace.off(event, [handler])`: Unbind the provided `event` and `handler` combination.
198+
- `Pace.once(event, handler, [context])`: Bind `handler` to the next (and only the next) incidence of `event`
199+
200+
Tracking
201+
--------
202+
203+
By default, Pace will show any ajax requests which begin as a part of a normal or ajax-y page load, or which last longer than
204+
500ms.
205+
206+
You can disable all ajax tracking by setting `ajax` to false:
207+
208+
```javascript
209+
Pace.options = {
210+
ajax: false
211+
}
212+
```
213+
214+
You can disable ajax tracking except on page navigation by setting `restartOnRequestAfter` to false:
215+
216+
```javascript
217+
Pace.options = {
218+
restartOnRequestAfter: false
219+
}
220+
```
221+
222+
You can manually disable tracking for a specific request or requests by triggering them within a `Pace.ignore` callback:
223+
224+
```javascript
225+
Pace.ignore(function(){
226+
$.ajax(...)
227+
});
228+
```
229+
230+
You can force the progress bar to be shown for a specific request by triggering them within a `Pace.track` callback:
231+
232+
```javascript
233+
Pace.track(function(){
234+
$.ajax(...)
235+
});
236+
```
237+
238+
You can also ignore URLs based on a pattern:
239+
240+
```javascript
241+
Pace.options = {
242+
ajax: {
243+
ignoreURLs: ['some-substring', /some-regexp/]
244+
}
245+
}
246+
```
247+
248+
Dependencies
249+
------------
250+
251+
None!
252+
253+
Support
254+
-------
255+
256+
Pace is designed to support IE8+ (standards mode), FF 3.5+, Chrome, Safari 4+, Opera 10.5+, and all modern
257+
mobile browsers. If you run into a compatibility issue, or can make a case for supporting something else,
258+
please create an issue.
259+
260+
Size
261+
----
262+
263+
pace.js is 4kb minified and gzipped. The themes vary between 0.5 and 4kb.
264+
265+
Issues
266+
------
267+
268+
We have obviously not tested this on every website. If you run into an issue, or find a way the automatic
269+
detection could be better, please [create an Issue](https://github.com/CodeByZach/pace/issues/new). If you can include a test case, that's even better.
270+
271+
Credits
272+
-------
273+
274+
[HubSpot](http://dev.hubspot.com)
275+
276+
Javascript by [Zack Bloom](http://twitter.com/zackbloom)
277+
CSS by [Adam Schwartz](http://twitter.com/adamfschwartz)
278+
279+
Themes inspired by [Mary Lou](http://tympanus.net/codrops/2013/09/18/creative-loading-effects/)
280+
281+
Project inspired by [nprogress](http://ricostacruz.com/nprogress/)

0 commit comments

Comments
 (0)