Merge pull request #7 from kimuraz/vuepress

Vuepress

Author: kimuraz

.gitignore

@@ -4,7 +4,9 @@ dist/
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+test/unit/coverage
 coverage/
+deploy-docs.sh
 
 # Editor directories and files
 .editorconfig

README.md

@@ -1,17 +1,23 @@
 [![Build Status](https://travis-ci.org/kimuraz/vue-rest.svg?branch=dev)](https://travis-ci.org/kimuraz/vue-rest)
 # vue-rest
 
-> Plugin for using vue + axios for REST API consumption
+Plugin for using vue + axios for REST API CRUD operations
 
 ## Installation
 
 ```shell
 $ npm i -S vue-rest
+
+OR
+
+$ yarn add vue-rest
 ```
 
 ## Documentation
 
-[Gitbook](https://kimuraz.gitbooks.io/vue-rest/content/)
+Checkout the docs:
+
+:book: [Docs](https://kimuraz.github.io/vue-rest/)
 
 ## Examples
 

assets/vue-rest.png

@@ -0,0 +1,38 @@
+module.exports = {
+  base: '/vue-rest/',
+  title: 'Vue Rest',
+  description: 'A fast way to make REST cruds',
+  serviceWorker: false,
+  themeConfig: {
+    repo: 'kimuraz/vue-rest',
+    editLinks: true,
+    docsDir: 'docs',
+    locales: {
+      '/': {
+        label: 'Home',
+        editLinkText: 'Edit this page on GitHub',
+        lastUpdated: 'Last Updated',
+        nav: [
+          {
+            text: 'Getting started',
+            link: '/started.md'
+          },
+          {
+            text: '$api',
+            link: '/prototype.md'
+          },
+          {
+            text: 'Mixins',
+            link: '/mixins.md'
+          }
+        ],
+        sidebar: [
+          'intro.md',
+          'started.md',
+          'prototype.md',
+          'mixins.md'
+        ]
+      }
+    }
+  }
+}

docs/.vuepress/config.js

@@ -0,0 +1,14 @@
+---
+home: true
+heroImage: /vue-rest.png
+actionText: Get Started →
+actionLink: intro.md
+features:
+- title: Easy
+  details: Use etiher the $api prototype or one of the plugins 
+- title: Axios
+  details: It uses axios as requests library
+- title: CRUD operations faster
+  details: Use save() to save your form or load() to load you list
+footer: MIT Licensed | Copyright © 2018 J. Eduardo Kimura Reis
+---

docs/.vuepress/public/vue-rest.png

@@ -0,0 +1,9 @@
+# Vue Rest Docs
+
+The vue-rest plugin was developed to help in VueJS applications that needs API request to do CRUD operations.
+
+It implements two mixins: ApiList and ApiForm, and a prototype: $api.
+
+I believe through this mixins you will be able to implement easily any CRUD that you need.
+
+You're welcome to contribute to the project.

docs/README.md

@@ -0,0 +1,136 @@
+# Mixins
+
+## ApiForm
+### Intro
+
+The ApiForm is responsible for implementing the methods for API requesting that usually a form does.
+
+It requires a `route prop` and, for convenience, can handle two others props `objId` and `obj`. Both props are handled in mixin's `created()` hook, and the `obj` sets the `requestObj` data to its value and the `objId` loads a new instance of a object to `requestObj` returned from API in the `load()` method.
+
+> See: [Vue Lifecycle Hooks](https://vuejs.org/v2/guide/instance.html#Instance-Lifecycle-Hooks)
+
+### Methods
+
+The following methods are implemented through this mixin:
+
+`load(id, errCallback)`:
+
+- Params: id, errCallback
+
+- Functionality: It does a GET request to the given route /id and loads the response.data to the requestObj data.
+
+`save(callback, errCallback)`:
+- Params: callback, errCallback
+- Functionality: It passes the received callback and errCallback to one of the following methods:
+    - If the `requestObj` has an id `(requestObj.id)`:
+        * `update(callback, errCallback)`:
+            - Params: callback, errCallback
+            - Functionality: It uses the $api prototype to do a PATCH requests using the given route and passing the requestObj as payload, passing the success response to the callback function and if there's any error it passes the it to the errCallback function.
+    - Otherwise:
+        * create(callback, errCallback):
+            - Params: callback, errCallback
+            - Functionality: It does the same thing as the update method but instead of a PATCH it does a POST to the API.`
+
+### Using it
+
+> Note that you need to pass a `route` prop or override the prop as:
+>
+> `route: { required: false, default: 'your-route' }`
+
+```vue
+<template>
+    <form @submit.prevent="save(showOk, showErr)">
+        <input v-model="requestObj.firstName"/>
+        <input v-model="requestObj.lastName"/>
+        <button type="submit">
+            Add
+        </button>
+    </form>
+</template>
+
+<script>
+import { ApiForm } from 'vue-rest'
+
+export default {
+    name: 'personForm',
+    mixins: [ApiForm],
+    methods: {
+        showOk(res) {
+            console.log(res)
+            alert('Sucessfully saved')
+        },
+        showErr(err) {
+            console.log(err)
+            alert(`An error ocurred: ${err}`)
+        }
+    }
+}
+</script>
+```
+
+
+## ApiList
+### Intro
+
+The ApiList is responsible for implementing a route mandatory prop and the three following methods to load and handle list actions:
+
+
+### Methods
+
+`loadList(callback, errCallback)`:
+
+- Params: callback, errCallback
+- Functionality: It uses $api prototype to do a GET request in the given route and pass the response for the callback function if the response was successfully made, otherwise passes the error to the errCallback function.
+
+`deleteObj(objId, callback, errCallback)`:
+
+- Params: objId, callback, errCallback
+- Functionality: It uses $api prototype to do a DELETE request in the given route concatenated with the objIdand passes the response for the callback function if the response was successfully made, then it emits a delete event with the objId.
+
+`editObj(obj)`:
+
+- Params: obj
+- Functionality: It just emits an edit event with the given obj in its value.
+
+> Note: You should probably handle the emitted value to pass to a ApiForm instance
+
+
+### Using it
+```vue
+<template>
+    <ul>
+        <li v-for="p in people" :key="p.id">
+            {{ p.firstName }} {{ p.lastName }}
+        </li>
+    </ul>
+</template>
+
+<script>
+import { ApiList } from 'vue-rest'
+
+export default {
+    name: 'peopleList',
+    mixins: [ApiList],
+    data() {
+        return {
+            people: [],
+        }
+    },
+    created() {
+        this.loadList(this.loadPeople, this.showErr)
+    },
+    methods: {
+        loadPeople(res) {
+            console.log(res)
+            this.people = [...res.data.results]
+        },
+        showErr(err) {
+            console.log(err)
+            alert(`An error ocurred ${err}`)
+        }
+    }
+}
+
+</script>
+
+```

docs/intro.md

@@ -0,0 +1,21 @@
+# The $api prototype
+
+The $api prototype is a wrapper for [axios](https://github.com/mzabriskie/axios) and you can use it easily anywhere in your application, it accepts the same options that axios does, just pass the option object when setting VueRest up (see [Adding to your project](started.md)).
+
+Example:
+
+```js
+export default {
+  name: 'foodList',
+  data() {
+    return {
+      ingredients: []
+    }
+  },
+  created() {
+    this.$api.get('/ingredients').then(res => {
+      this.ingredients = res.data.results
+    })
+  }
+}
+```

docs/mixins.md

@@ -0,0 +1,55 @@
+# Getting Started
+
+## Installing
+
+To install the plugin simply do:
+
+```sh
+$ yarn add vue-rest
+
+# OR
+
+$ npm install vue-rest
+```
+
+## Adding to your project
+
+To add to your project, import it and the use `Vue.use(VueRest)` to properly use it.
+
+> Optionally you can add `axiosOptions` that is responsible for any options related to [axios]('https://github.com/mzabriskie/axios%29/')
+
+```js
+...
+import VueRest from 'vue-rest';
+...
+
+Vue.use(VueRest, {
+  axiosOptions: {
+    baseURL: 'http://localhost/api/',
+  }
+});
+```
+
+## Using ApiForm and ApiList
+
+These two mixins implements some methods, props and data to your component, to use them, do:
+
+```js
+import { ApiForm } from 'vue-rest';
+
+export default {
+  ...
+  mixins: [ApiForm]
+  ...
+}
+```
+
+```js
+import { ApiList } from 'vue-rest';
+
+export default {
+  ...
+  mixins: [ApiList]
+  ...
+}
+```