76 lines
8.3 KiB
HTML
76 lines
8.3 KiB
HTML
<h1 id="NProgress"><a href="#NProgress" class="headerlink" title="NProgress"></a>NProgress</h1><p>Slim progress bars for Ajax’y applications. Inspired by Google, YouTube, and<br>Medium.</p>
|
||
<h2 id="Installation"><a href="#Installation" class="headerlink" title="Installation"></a>Installation</h2><p>Add <a href="http://ricostacruz.com/nprogress/nprogress.js">nprogress.js</a> and <a href="http://ricostacruz.com/nprogress/nprogress.css">nprogress.css</a> to your project.</p>
|
||
<pre><code class="html"><script src='nprogress.js'></script>
|
||
<link rel='stylesheet' href='nprogress.css'/>
|
||
</code></pre>
|
||
<p>NProgress is available via <a href="http://bower.io/search/?q=nprogress">bower</a> and <a href="https://www.npmjs.org/package/nprogress">npm</a> and <a href="http://spmjs.io/package/nprogress">spm</a>.</p>
|
||
<pre><code>$ bower install --save nprogress
|
||
$ npm install --save nprogress
|
||
</code></pre>
|
||
<h2 id="Basic-usage"><a href="#Basic-usage" class="headerlink" title="Basic usage"></a>Basic usage</h2><p>Simply call <code>start()</code> and <code>done()</code> to control the progress bar.</p>
|
||
<pre><code class="js">NProgress.start();
|
||
NProgress.done();
|
||
</code></pre>
|
||
<p>Using <a href="https://github.com/rails/turbolinks">Turbolinks</a> or similar? Ensure you’re using Turbolinks 1.3.0+, and use<br>this: (explained<br> <a href="https://github.com/rstacruz/nprogress/issues/8#issuecomment-23010560">here</a>)</p>
|
||
<pre><code class="js">$(document).on('page:fetch', function() { NProgress.start(); });
|
||
$(document).on('page:change', function() { NProgress.done(); });
|
||
$(document).on('page:restore', function() { NProgress.remove(); });
|
||
</code></pre>
|
||
<h2 id="Ideas"><a href="#Ideas" class="headerlink" title="Ideas"></a>Ideas</h2><ul>
|
||
<li><p>Add progress to your Ajax calls! Bind it to the jQuery <code>ajaxStart</code> and<br> <code>ajaxStop</code> events.</p>
|
||
</li>
|
||
<li><p>Make a fancy loading bar even without Turbolinks/Pjax! Bind it to<br> <code>$(document).ready</code> and <code>$(window).load</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<h2 id="Advanced-usage"><a href="#Advanced-usage" class="headerlink" title="Advanced usage"></a>Advanced usage</h2><p><strong>Percentages:</strong> To set a progress percentage, call <code>.set(n)</code>, where <em>n</em> is a<br>number between <code>0..1</code>.</p>
|
||
<pre><code class="js">NProgress.set(0.0); // Sorta same as .start()
|
||
NProgress.set(0.4);
|
||
NProgress.set(1.0); // Sorta same as .done()
|
||
</code></pre>
|
||
<p><strong>Incrementing:</strong> To increment the progress bar, just use <code>.inc()</code>. This<br>increments it with a random amount. This will never get to 100%: use it for<br>every image load (or similar).</p>
|
||
<pre><code class="js">NProgress.inc();
|
||
</code></pre>
|
||
<p>If you want to increment by a specific value, you can pass that as a parameter:</p>
|
||
<pre><code class="js">NProgress.inc(0.2); // This will get the current status value and adds 0.2 until status is 0.994
|
||
</code></pre>
|
||
<p><strong>Force-done:</strong> By passing <code>true</code> to <code>done()</code>, it will show the progress bar<br>even if it’s not being shown. (The default behavior is that <em>.done()</em> will not<br> do anything if <em>.start()</em> isn’t called)</p>
|
||
<pre><code class="js">NProgress.done(true);
|
||
</code></pre>
|
||
<p><strong>Get the status value:</strong> To get the status value, use <code>.status</code></p>
|
||
<h2 id="Configuration"><a href="#Configuration" class="headerlink" title="Configuration"></a>Configuration</h2><h4 id="minimum"><a href="#minimum" class="headerlink" title="minimum"></a><code>minimum</code></h4><p>Changes the minimum percentage used upon starting. (default: <code>0.08</code>)</p>
|
||
<pre><code class="js">NProgress.configure({ minimum: 0.1 });
|
||
</code></pre>
|
||
<h4 id="template"><a href="#template" class="headerlink" title="template"></a><code>template</code></h4><p>You can change the markup using <code>template</code>. To keep the progress<br>bar working, keep an element with <code>role='bar'</code> in there. See the <a href="https://github.com/rstacruz/nprogress/blob/master/nprogress.js#L31">default template</a><br>for reference.</p>
|
||
<pre><code class="js">NProgress.configure({
|
||
template: "<div class='....'>...</div>"
|
||
});
|
||
</code></pre>
|
||
<h4 id="easing-and-speed"><a href="#easing-and-speed" class="headerlink" title="easing and speed"></a><code>easing</code> and <code>speed</code></h4><p>Adjust animation settings using <em>easing</em> (a CSS easing string)<br>and <em>speed</em> (in ms). (default: <code>ease</code> and <code>200</code>)</p>
|
||
<pre><code class="js">NProgress.configure({ easing: 'ease', speed: 500 });
|
||
</code></pre>
|
||
<h4 id="trickle"><a href="#trickle" class="headerlink" title="trickle"></a><code>trickle</code></h4><p>Turn off the automatic incrementing behavior by setting this to <code>false</code>. (default: <code>true</code>)</p>
|
||
<pre><code class="js">NProgress.configure({ trickle: false });
|
||
</code></pre>
|
||
<h4 id="trickleRate-and-trickleSpeed"><a href="#trickleRate-and-trickleSpeed" class="headerlink" title="trickleRate and trickleSpeed"></a><code>trickleRate</code> and <code>trickleSpeed</code></h4><p>You can adjust the <em>trickleRate</em> (how much to increase per trickle) and<br><em>trickleSpeed</em> (how often to trickle, in ms).</p>
|
||
<pre><code class="js">NProgress.configure({ trickleRate: 0.02, trickleSpeed: 800 });
|
||
</code></pre>
|
||
<h4 id="showSpinner"><a href="#showSpinner" class="headerlink" title="showSpinner"></a><code>showSpinner</code></h4><p>Turn off loading spinner by setting it to false. (default: <code>true</code>)</p>
|
||
<pre><code class="js">NProgress.configure({ showSpinner: false });
|
||
</code></pre>
|
||
<h4 id="parent"><a href="#parent" class="headerlink" title="parent"></a><code>parent</code></h4><p>specify this to change the parent container. (default: <code>body</code>)</p>
|
||
<pre><code class="js">NProgress.configure({ parent: '#container' });
|
||
</code></pre>
|
||
<h2 id="Customization"><a href="#Customization" class="headerlink" title="Customization"></a>Customization</h2><p>Just edit <code>nprogress.css</code> to your liking. Tip: you probably only want to find<br>and replace occurrences of <code>#29d</code>.</p>
|
||
<p>The included CSS file is pretty minimal… in fact, feel free to scrap it and<br>make your own!</p>
|
||
<h2 id="Resources"><a href="#Resources" class="headerlink" title="Resources"></a>Resources</h2><ul>
|
||
<li><a href="http://www.usabilitypost.com/2013/08/19/new-ui-pattern-website-loading-bars/">New UI Pattern: Website Loading Bars</a> (usabilitypost.com)</li>
|
||
</ul>
|
||
<h2 id="Support"><a href="#Support" class="headerlink" title="Support"></a>Support</h2><p><strong>Bugs and requests</strong>: submit them through the project’s issues tracker.<br><br><a href="https://github.com/rstacruz/nprogress/issues"><img src="http://img.shields.io/github/issues/rstacruz/nprogress.svg" alt="Issues"></a></p>
|
||
<p><strong>Questions</strong>: ask them at StackOverflow with the tag <em>nprogress</em>.<br><br><a href="http://stackoverflow.com/questions/tagged/nprogress"><img src="http://img.shields.io/badge/stackoverflow-nprogress-brightgreen.svg" alt="StackOverflow"></a></p>
|
||
<p><strong>Chat</strong>: join us at gitter.im.<br><br><a href="https://gitter.im/rstacruz/nprogress"></a></p>
|
||
<h2 id="Thanks"><a href="#Thanks" class="headerlink" title="Thanks"></a>Thanks</h2><p><strong>NProgress</strong> © 2013-2014, Rico Sta. Cruz. Released under the <a href="http://mit-license.org/">MIT License</a>.<br><br>Authored and maintained by Rico Sta. Cruz with help from <a href="http://github.com/rstacruz/nprogress/contributors">contributors</a>.</p>
|
||
<blockquote>
|
||
<p><a href="http://ricostacruz.com/">ricostacruz.com</a> &nbsp;&middot;&nbsp;<br>GitHub <a href="https://github.com/rstacruz">@rstacruz</a> &nbsp;&middot;&nbsp;<br>Twitter <a href="https://twitter.com/rstacruz">@rstacruz</a></p>
|
||
</blockquote>
|
||
<p><a href="http://travis-ci.org/rstacruz/nprogress"><img src="https://api.travis-ci.org/rstacruz/nprogress.svg?branch=master" alt="Status"></a><br><a href="https://npmjs.org/package/nprogress" title="View this project on npm"><img src="https://img.shields.io/npm/v/nprogress.png" alt="npm version"></a><br><a href="http://spmjs.io/package/nprogress"><img src="http://spmjs.io/badge/nprogress" alt="spm package"></a></p>
|