Added better documentation. Restructured the code to allow for usage …

…in browser without a build step. Cleaned up the API.
rigor789 · Mar 18, 2017 · 8080fe3 · 8080fe3
1 parent 919eb80
commit 8080fe3
Show file tree

Hide file tree

Showing 24 changed files with 1,009 additions and 496 deletions.
diff --git a/.npmignore b/.npmignore
@@ -1,3 +1,4 @@
 node_modules
 .editorconfig
-.idea
+.idea
+docs
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,158 @@
+# vue-scrollto
+
+[![Vue 2.x](https://img.shields.io/badge/Vue-2.x-brightgreen.svg)](https://vuejs.org/v2/guide/)
+[![npm](https://img.shields.io/npm/v/vue-scrollto.svg)](https://www.npmjs.com/package/vue-scrollto)
+[![npm-downloades](https://img.shields.io/npm/dm/vue-scrollto.svg)](https://www.npmjs.com/package/vue-scrollto)
+[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/rigor789/vue-scrollto/blob/master/LICENSE)
+
+[DEMO](https://rigor789.github.io/vue-scrollto/)
+
+Scrolling to elements was never this easy!
+
+This is for `vue 2.x`
+
+For `vue 1.x` use `v...` but keep in mind that the old version depends on `jquery`.
+
+## Under the hood
+
+`vue-scrollto` uses `window.requestAnimationFrame` to perform the animations, thus giving the best performance.
+
+Easing is done using [bezier-easing]() - A well tested easing micro-library.
+
+<p class="tip">
+It even knows when the user interrupts, and doesn't force scrolling that would result in bad UX.
+</p>
+
+## Installing
+
+This package is available on npm.
+
+Using npm:
+```bash
+npm install --save vue-scrollto
+```
+
+Alternatively you can use yarn:
+```bash
+yarn add vue-scrollto
+```
+
+<p class="warning">
+    If you used this package before, please ensure you are using the right one, since it has been renamed from `vue-scrollTo` to `vue-scrollto`
+</p>
+
+
+## Usage
+
+vue-scrollto can be used either as a vue directive, or programatically from your javascript.
+
+### As a vue directive
+```js
+var Vue = require('vue');
+var VueScrollTo = require('vue-scrollto');
+
+Vue.use(VueScrollTo)
+```
+
+```html
+<a href="#" v-scroll-to="'#element'">Scroll to #element</a>
+
+<div id="element">
+    Hi. I'm #element.
+</div>
+```
+
+If you need to customize the scrolling options, you can pass in an object literal to the directive:
+
+```html
+<a href="#" v-scroll-to="{
+     el: '#element',
+     container: '#container',
+     duration: 500,
+     easing: 'linear',
+     offset: -200,
+     onDone: onDone,
+     onCancel: onCancel
+ }">
+    Scroll to #element
+</a>
+```
+
+<p class="tip">
+    Check out the [Options Section](#options) for more details about the available options.
+</p>
+
+### Programatically
+
+```js
+var VueScrollTo = require('vue-scrollto');
+
+var options = {
+    container: '#container',
+    easing: vueScrollto.easing['ease-in'],
+    offset: -60,
+    onDone: function() {
+      // scrolling is done
+    },
+    onCancel: function() {
+      // scrolling has been interrupted
+    }
+}
+
+VueScrollTo.scrollTo(element, duration, options)
+```
+
+## Options
+
+#### el / element 
+The element you want to scroll to.
+
+#### container
+The container that has to be scrolled. 
+
+*Default:* `body`
+
+#### duration
+The duration (in milliseconds) of the scrolling animation. 
+
+*Default:* `1000` 
+
+#### easing 
+The easing to be used when animating. Read more in the [Easing section](#easing). 
+
+*Default:* `ease`
+
+#### offset 
+The offset that should be applied when scrolling. 
+
+*Default:* `0`
+
+#### onDone 
+A callback function that should be called when scrolling has ended. 
+
+*Default:* `noop`
+
+#### onCancel 
+A callback function that should be called when scrolling has been aborted by the user (user scrolled, clicked etc.).
+
+*Default:* `noop`
+
+
+## Easing
+
+Easing is calculated using [bezier-easing]() so you can pass your own values into `options.easing` in the form of an array with 4 values.
+
+vue-scrollto defines the following easings that you can use:
+```js
+exports.easing = {
+    'ease': [0.25, 0.1, 0.25, 1.0],
+    'linear': [0.00, 0.0, 1.00, 1.0],
+    'ease-in': [0.42, 0.0, 1.00, 1.0],
+    'ease-out': [0.00, 0.0, 0.58, 1.0],
+    'ease-in-out': [0.42, 0.0, 0.58, 1.0]
+}
+```
+
+## License
+
+MIT
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,34 @@
+## [v2.5.4](https://github.com/rigor789/vue-scrollto/commit/919eb807bae8bf6eb201462d4f9923f7bc6c56b5) (2017-3-15)
+
+### Bug fixes
+- Fixed jumping to the top of the page in firefox when scrolling on the `body` tag. [6f5615e](https://github.com/rigor789/vue-scrollto/commit/6f5615ebe8602bf766e1401d33c6b1c24a961db2)
+
+## [v2.5.3](https://github.com/rigor789/vue-scrollto/commit/1b6ee1380401545897f7403a720d75d97665c219) (2017-3-14)
+
+### Additions
+- Added calculations for scrolling inside positioned elements. [7f730e8](https://github.com/rigor789/vue-scrollto/commit/7f730e82cbe0d585aa7ebd783eaf9761bc4add28)
+
+## [v2.5.2](https://github.com/rigor789/vue-scrollto/commit/d5aaf39b5c3584f40b298d1279d2a94a4dd9c940) (2017-3-14)
+
+### Bug fixes
+- Fixed firefox not scrolling on `body` tag. [575d90a](https://github.com/rigor789/vue-scrollto/commit/575d90ab3d60ae6fec9027fea1f72a3ffacd440b)
+
+## [v2.5.1](https://github.com/rigor789/vue-scrollto/commit/e0970507d51529583e237aa4c69dcede4896af73) (2017-3-14)
+
+### Additions
+- Added examples for using the `container` option
+
+## [v2.5.0](https://github.com/rigor789/vue-scrollto/commit/7abe2bb111964f173b003208c0f28eb3b6e209fd) (2017-3-14)
+
+### Additions
+- Added `container` option to allow scrolling inside different containers
+
+## [v2.4.2](https://github.com/rigor789/vue-scrollto/commit/aa1cca9afc95adce564fbd976eca369aaa704917) (2017-3-6)
+
+### Changes
+- Updated the repository link in `package.json`
+
+## [v2.4.1](https://github.com/rigor789/vue-scrollto/commit/bdbc6409c72ba0217348aa4cc5d9c93df9441a30) (2017-3-6)
+
+### Changes
+- Renamed package from `vue-scrollTo` to `vue-scrollto` due to npm's limited support for capital letters in package names.
diff --git a/docs/examples.html b/docs/examples.html
@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport"
+          content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+    <meta http-equiv="X-UA-Compatible" content="ie=edge">
+    <title>Examplese</title>
+</head>
+<body>
+
+<div id="app">
+    <h1>{{ msg }}</h1>
+
+    <button v-scroll-to="'#element'">Go</button>
+    <button v-scroll-to="{el:'#element'}">Go</button>
+    <button v-scroll-to="{element:'#element'}">Go</button>
+    <button v-scroll-to="{element:'#element', easing: 'ease-out', duration: 5000}">Go</button>
+    <button v-scroll-to="{element:'#element', easing: [.6, -.80, .30, 1.9], duration: 2000}">Go</button>
+    <button v-scroll-to="{element:'#element', offset: 200}">Go</button>
+    <button v-scroll-to="{element:'#element', onDone: onDone, onCancel: onCancel, duration: 4000}">Go</button>
+    <div style="height: 2000px; background: #eee;"></div>
+    <h1 id="element">Hi</h1>
+    <div style="height: 200px; background: #4fc08d;"></div>
+    <div style="height: 2000px; background: #eee;"></div>
+</div>
+
+<script src="https://unpkg.com/[email protected]"></script>
+<script src="../vue-scrollto.js"></script>
+
+<script>
+    new Vue({
+        el: '#app',
+
+        data: {
+            msg: 'vue-scrollto'
+        },
+
+        methods: {
+            onDone() {
+                alert('done')
+            },
+            onCancel(e) {
+                console.log(e)
+            }
+        }
+    })
+</script>
+</body>
+</html>
diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,95 @@
+# Examples
+
+Here are some examples of `vue-scrollto`!
+
+Every example assumes you have installed `vue-scrollto`:
+```js
+const Vue = require('vue')
+const VueScrollTo = require('vue-scrollto')
+Vue.use(VueScrollTo)
+```
+
+## Using string literals
+
+```html
+<button v-scroll-to="'#element'">
+    Scroll to #element
+</button>
+
+<h1 id="element">Hi. I'm element</h1>
+```
+
+## Using object literals
+
+```html
+<button v-scroll-to="{ el: '#element' }">
+    Scroll to #element
+</button>
+```
+or
+```html
+<button v-scroll-to="{ element: '#element' }">
+    Scroll to #element
+</button>
+```
+
+#### Using a different duration
+
+```html
+<button v-scroll-to="{ element: '#element', duration: 5000 }">
+    Scroll to #element
+</button>
+```
+
+#### Using a different easing
+
+```html
+<button v-scroll-to="{ element: '#element', easing: 'linear' }">
+    Scroll to #element
+</button>
+```
+
+#### Using custom easing combined with duration
+
+```html
+<button v-scroll-to="{ 
+        el: '#element',
+        easing: [.6, -.80, .30, 1.9],
+        duration: 2000 
+    }">
+    Scroll to #element
+</button>
+```
+
+#### Using offset
+
+```html
+<button v-scroll-to="{ el: '#element', offset: 200 }">
+    Scroll to 200px below #element 
+</button>
+```
+
+#### Adding callbacks
+```html
+<button v-scroll-to="{ 
+        el: '#element',
+        onDone: onDone,
+        onCancel: onCancel
+    }">
+    Scroll callbacks
+</button>
+```
+
+```js
+export default {
+    methods: {
+        onDone() {
+            // do something
+        },
+
+        onCancel() {
+            // do something
+        }
+    }
+}
+```
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html>
+<head lang="en">
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
+    <title>vue-scrollto</title>
+    <link rel="stylesheet" href="https://unpkg.com/docute@2/dist/docute.css">
+</head>
+<body>
+<div id="app"></div>
+<script src="https://unpkg.com/docute@2/dist/docute.js"></script>
+<script src="https://unpkg.com/docute-iframe"></script>
+<script>
+    docute.init({
+        repo: 'rigor789/vue-scrollto',
+        twitter: 'igor_randj',
+
+        landing: true,
+
+        debug: true,
+
+        plugins: [
+            docuteIframe()
+        ],
+
+        nav: [
+            {title: 'Home', path: '/'},
+            {title: 'Getting Started', path: '/docs', source: 'README.md'},
+            {title: 'Examples', path: '/examples', $source: 'examples.html'},
+            {title: 'Changelog', path: '/changelog'},
+        ]
+    })
+</script>
+</body>
+</html>