Add docs

Author: kiaking

docs/.vuepress/config.js

@@ -5,6 +5,9 @@ const sidebars = {
       collapsable: false,
       children: [
         '/guide/installation',
+        '/guide/getting-started',
+        '/guide/basic-usage',
+        '/guide/configurations',
         '/guide/sponsors'
       ]
     },

docs/api/model.md

@@ -4,4 +4,42 @@ sidebarDepth: 2
 
 # Model
 
-Coming soon...
+Vuex ORM Axios adds a few properties and methods to the Model object.
+
+## Static Properties
+
+### axios
+
+- **`static axios: AxiosInstance | null`**
+
+  The axios isntance which was installed during the plugin installation process. Vuex ORM Axios adds a few properties and methods to the Model object. Vuex ORM Axios will use this Axios instance to perform any HTTP request.
+
+  Usually, this property will not become `null`. However, there's a case where you may need to add Axios instance manually, for example, when using Vuex ORM Axios with Nuxt.js. Int hat case, this property will temporary be `null`.
+
+### globalApiConfig
+
+- **`globalApiConfig: GlobalConfig`**
+
+  The property that holds global configuration. The value will be set automatically during the plugin installation process. **Do not mutate this property manually**.
+
+- **`apiConfig: Config | null`**
+
+  The property that defines the Model configuration for the API call.
+
+## Static Methods
+
+### setAxios
+
+- **`static setAxios(axios: AxiosInstance): void`**
+
+  The method to set the Axios instance manually. Usually, you don't have to call this method yourself. However, you might need to use this method to set Axios instance properly in some situations. Please [refer here](../guide/getting-started.html#nuxt-js-integration) for more detail.
+
+### api
+
+- **`static api(): Request`**
+
+  This method is going to return a new Request instance. Request instance is the wrapper for Axios, and it's used to perform any API request.
+
+  ```js
+  User.api().get('/api/users')
+  ```

docs/guide/basic-usage.md

@@ -0,0 +1,76 @@
+# Basic Usage
+
+After setting up Vuex ORM Axios, you may use `Model.api` method to perform api call.
+
+```js
+User.api().get('/api/users')
+```
+
+## Request
+
+Vuex ORM Axios can perform all basic Axios requests, which is `get`, `post`, `put`, `patch`, `delete`, and `request`. These methods take the same arguments as Axios and perform exactly as same as Axios, except it's going to store response data to the store corresponding to the Model that is calling the api.
+
+Available methods and the argument pattern is listed below. Remember, the argument is the same as the corresponding Axios methods. The `data` or `config` will be passed directly to the underlining Axios instance.
+
+```js
+User.api().get(url, config)
+User.api().post(url, data, config)
+User.api().put(url, data, config)
+User.api().patch(url, data, config)
+User.api().delete(url, config)
+User.api().request(config)
+```
+
+When calling any of the above methods, Vuex ORM Axios will persist the response data to the store. Let's say your api response is as follows.
+
+```js
+// Response body data.
+
+{
+  "id": 1,
+  "name": "John Doe",
+  "age": 24
+}
+```
+
+And if you call api from User Model, the above data will be inserted as User records to the store.
+
+```js
+// Call api from User Model.
+User.api().get('/api/users')
+
+// Then, inside Vuex Store.
+{
+  users: {
+    data: {
+      1: { id: 1, name: 'John Doe', age: 24 }
+    }
+  }
+}
+```
+
+Now, remember that Vuex ORM Axios will try to insert any response data to the store. For example, if you call the same API from Post Model, it's going to try to insert the response as Post records. So be aware of what Model to call the API from.
+
+Also, note that these methods can take the same configuration as Axios.
+
+```js
+User.api().get('users', {
+  baseURL: 'https://example.com/api/'
+})
+```
+
+There're additional configuration specific to Vuex ORM Axios as well. Please check out [Configurations page](configurations) for more.
+
+## Response
+
+The response object is a bit different from Axios response and contains 2 properties. One is `response`, which is the pure Axios response object, and the second one is the `entities`, which holds Vuex ORM persistent result.
+
+```js
+const result = await User.api().get('/api/users')
+
+// You may access Axios response object like this.
+result.response.status // <- 200
+
+// And Vuex ORM persisted entities like so.
+result.entities // <- { users: [{ ... }] }
+```

docs/guide/configurations.md

@@ -0,0 +1,84 @@
+# Configurations
+
+You may configure many options in Vuex ORM Axios and its underlining Axios instance. There are 3 places to set options.
+
+- Global Configuration
+- Model Configuration
+- Request Configuration
+
+Global Configuration can be defined at the installation process by passing the option as the second argument of `VuexORM.use` method.
+
+```js
+import axios from 'axios'
+import VuexORM from '@vuex-orm/core'
+import VuexORMAxios from '@vuex-orm/plugin-axios'
+
+VuexORM.use(VuexORMAxios, {
+  axios,
+  headers: {'X-Requested-With': 'XMLHttpRequest'},
+  baseURL: 'https://example.com/api/'
+})
+```
+
+You may define configuration at the Model level too. To do so, define `static apiConfig` property to the Model.
+
+```js
+import { Model } from '@vuex-orm/core'
+
+class User extends Model {
+  static entity = 'users'
+
+  static fields () {
+    return {
+      id: this.attr(null),
+      name: this.attr('')
+    }
+  }
+
+  static apiConfig = {
+    headers: {'X-Requested-With': 'XMLHttpRequest'},
+    baseURL: 'https://example.com/api/'
+  }
+}
+```
+
+Finally, you can pass configuration when making the api call.
+
+```js
+User.api().get('/api/users', {
+  headers: {'X-Requested-With': 'XMLHttpRequest'},
+  baseURL: 'https://example.com/api/'
+})
+```
+
+The lower level configuration will overwrite a higher level of configs. Which means that the Request Config will overwrite Model Config, and Model Config will overwrite Global Config.
+
+## Available Options
+
+All Axios configurations are available. For those, please refer to [the Axios documentation](https://github.com/axios/axios#request-config). In addition to Axios options, Vuex ORM Axios takes few more options specific to the plugin usage.
+
+### dataKey
+
+- **`dataKey: string | null`**
+
+  ```js
+  {
+    ok: true,
+    data: {
+      id: 1,
+      name: 'John Doe'
+    }
+  }
+  ```
+
+  In this case, data persistent to the store will probably fail, since actual data is inside `data` key, but Vuex ORM Axios is going to insert whole object including `ok` property.
+
+  For these situations, you can use `dataKey` property to specify which key to look for data.
+
+  ```js
+  User.api().get('/api/users', {
+    dataKey: 'data'
+  })
+  ```
+
+  With the above config, the data inside `data` key will be inserted to the store.

docs/guide/getting-started.md

@@ -0,0 +1,84 @@
+# Setup
+
+This page is a quick start guide to begin using Vuex ORM. It assumes you have a basic understanding of Vuex ORM. If you are not familiar with Vuex ORM, please check out the [Vuex ORM Documentation](https://vuex-orm.github.io/vuex-orm/).
+
+At first, Vuex ORM Axios requires manually passing Axios instance during the installation process. Please make sure you have axios installed to your app.
+
+To install Vuex ORM Axios to Vuex ORM, pass Vuex ORM Axios to the `VuexORM.use` method. Here, you should pass your axios instance as an option.
+
+```js
+import axios from 'axios'
+import VuexORM from '@vuex-orm/core'
+import VuexORMAxios from '@vuex-orm/plugin-axios'
+
+VuexORM.use(VuexORMAxios, { axios })
+```
+
+Here is a more realistic example that shows how to install Vuex ORM to Vuex along with Vex ORM Axios.
+
+```js
+import axios from 'axios'
+import Veux from 'vuex'
+import VuexORM from '@vuex-orm/core'
+import VuexORMAxios from '@vuex-orm/plugin-axios'
+import User from '@/models/User'
+
+VuexORM.use(VuexORMAxios, { axios })
+
+const database = new VuexORM.Database()
+
+database.register(User)
+
+const store = new Vuex({
+  Plugins: [VuexORM.install(database)]
+})
+```
+
+## Nuxt.js Integration
+
+When using Vuex ORM Axios with Nuxt.js Axios Module, you can’t pass Axios instance directly from `store/index.js` file. Hence you must create a Nuxt.js plugin. Let's work through the process of setting up Vuex ORM Axios with Nuxt.js.
+
+First, leave `axios` option empty at the plugin installation part.
+
+```js
+// store/index.js
+
+import Veux from 'vuex'
+import VuexORM from '@vuex-orm/core'
+import VuexORMAxios from '@vuex-orm/plugin-axios'
+import User from '@/models/User'
+
+VuexORM.use(VuexORMAxios) // <- No axios option.
+
+const database = new VuexORM.Database()
+
+database.register(User)
+
+const plugins = [VuexORM.install(database)]
+```
+
+Next, create a plugin to set Axios instance to Vuex ORM Model directly.
+
+```js
+// plugins/vuex-orm-axios.js
+
+import { Model } from '@vuex-orm/core'
+
+export default ({ $axios }) => {
+  Model.setAxios($axios)
+}
+```
+
+Finally, don’t forget to register the plugin to `nuxt.config.js`.
+
+```js
+// nuxt.config.js
+
+export default {
+  // …
+
+  modules: ['@nuxtjs/axios'],
+
+  plugins: ['@/plugins/vuex-orm-axios']
+}
+```

docs/guide/installation.md

@@ -1,17 +1,17 @@
 # Installation
 
-You can install Vuex ORM Axios via NPM, Yarn, or download it directly. Remember since Vuex ORM Axios is a plugin of [Vuex ORM](https://github.com/vuex-orm/vuex-orm), you need to install Vuex ORM and Vuex alongside with Vuex ORM Axios.
+You can install Vuex ORM Axios via NPM, Yarn, or download it directly. Remember since Vuex ORM Axios is a plugin of [Vuex ORM](https://github.com/vuex-orm/vuex-orm), you need to install Vuex ORM and Vuex alongside with Vuex ORM Axios. Also, Vuex ORM Axios requires manually passing Axios Instance. Don't forget to install Axios as well.
 
 ## NPM
 
 ```console
-$ npm install vue vuex @vuex-orm/core @vuex-orm/plugin-axios --save
+$ npm install axios vue vuex @vuex-orm/core @vuex-orm/plugin-axios --save
 ```
 
 ## Yarn
 
 ```console
-$ yarn add vue vuex @vuex-orm/core @vuex-orm/plugin-axios
+$ yarn add axios vue vuex @vuex-orm/core @vuex-orm/plugin-axios
 ```
 
 ## Direct Download / CDN