You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,8 +21,10 @@
21
21
22
22
Vuex ORM Axios plugin adds smooth integration between API requests and [Vuex ORM](https://github.com/vuex-orm/vuex-orm) data persistence through the awesome [axios](https://github.com/axios/axios).
23
23
24
+
If you use axios with Vuex ORM, you may find handling requests can become an arduous and repetitive process. This plugin bridges Vuex ORM and axios and brings a unified process to perform requests and persist response data with ease.
25
+
24
26
```js
25
-
//Model API request...
27
+
//Example usage: fetch users and persist to store.
Copy file name to clipboardExpand all lines: docs/README.md
+30-19Lines changed: 30 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,20 @@
1
1
# Vuex ORM Axios
2
2
3
-
Vuex ORM Axios plugin adds smooth integration between API requests and [Vuex ORM](https://github.com/vuex-orm/vuex-orm) data persistence through the awesome [Axios](https://github.com/axios/axios).
3
+
Vuex ORM Axios plugin adds smooth integration between API requests and [Vuex ORM](https://github.com/vuex-orm/vuex-orm) data persistence through the awesome [axios](https://github.com/axios/axios).
4
+
5
+
If you use axios with Vuex ORM, you may find handling requests can become an arduous and repetitive process. This plugin bridges Vuex ORM and axios and brings a unified process to perform requests and persist response data with ease.
6
+
7
+
```js
8
+
// Example usage: fetch users and persist to store.
9
+
User.api().get('/api/users')
10
+
```
11
+
4
12
5
13
## Sponsors
6
14
7
15
Vuex ORM is sponsored by awesome folks. Big love to all of them from the whole Vuex ORM community :two_hearts:
8
16
9
-
### Super Love Sponsors
17
+
####Super Love Sponsors
10
18
11
19
<br>
12
20
@@ -22,6 +30,9 @@ Vuex ORM is sponsored by awesome folks. Big love to all of them from the whole V
Join us on our [Slack Channel](https://join.slack.com/t/vuex-orm/shared_invite/enQtNDQ0NjE3NTgyOTY2LTc1YTI2N2FjMGRlNGNmMzBkMGZlMmYxOTgzYzkzZDM2OTQ3OGExZDRkN2FmMGQ1MGJlOWM1NjU0MmRiN2VhYzQ) for any questions and discussions.
65
81
66
-
Although there is the Slack Channel, do not hesitate to open an [issue](https://github.com/vuex-orm/vuex-orm/issues) for any question you might have. We're always more than happy to hear any feedback, and we don't care what kind of form they are.
82
+
Although there is the Slack Channel, do not hesitate to open an [issue](https://github.com/vuex-orm/plugin-axios/issues) for any question you might have. We're always more than happy to hear any feedback, and we don't care what kind of form they are.
83
+
67
84
68
85
## Plugins
69
86
@@ -74,10 +91,4 @@ Vuex ORM can be extended via plugins to add additional features. Here is a list
74
91
-[Vuex ORM Change Flags](https://github.com/vuex-orm/plugin-change-flags) - Vuex ORM plugin for adding IsDirty / IsNew flags to model entities.
75
92
-[Vuex ORM Soft Delete](https://github.com/vuex-orm/plugin-soft-delete) – Vuex ORM plugin for adding soft delete feature to model entities.
76
93
77
-
## Resources
78
-
79
-
-[Vue](https://vuejs.org)
80
-
-[Vuex](https://vuex.vuejs.org)
81
-
-[Vuex ORM](https://vuex-orm.github.io/vuex-orm/)
82
-
83
-
You may find a list of awesome things related to Vuex ORM at [Awesome Vuex ORM](https://github.com/vuex-orm/awesome-vuex-orm).
94
+
You can find a list of awesome things related to Vuex ORM at [Awesome Vuex ORM](https://github.com/vuex-orm/awesome-vuex-orm).
You may configure many options in Vuex ORM Axios and its underlining Axios instance. There are 3 places to set options.
3
+
Vuex ORM Axios plugin comes with a wealth of options to control request behavior. These options can be configured in three common places:
4
4
5
-
-Global Configuration
6
-
- Model Configuration
7
-
- Request Configuration
5
+
-**Globally** - options can defined during installation
6
+
-**Model** - options can be defined on a per-model basis
7
+
-**Request** - options can be defined on a per-request basis
8
8
9
-
Global Configuration can be defined at the installation process by passing the option as the second argument of `VuexORM.use` method.
9
+
Any axios options are permitted alongside any plugin options. Options are inherited in the same order, i.e. Global configuration is merged and preceded by Model configuration which is then merged and preceded by any Request configuration.
10
+
11
+
### Global Configuration
12
+
13
+
Options can be defined during plugin installation by passing an object as the second argument of the Vuex ORM `use()` method. At minimum, the axios instance is required while any other option is entirely optional.
14
+
15
+
The following example configures the plugin with an axios instance (required), the `baseURL` option, and some common `headers` that all requests will inherit:
10
16
11
17
```js
12
18
importaxiosfrom'axios'
@@ -20,7 +26,11 @@ VuexORM.use(VuexORMAxios, {
20
26
})
21
27
```
22
28
23
-
You may define configuration at the Model level too. To do so, define `static apiConfig` property to the Model.
29
+
### Model Configuration
30
+
31
+
Options can be defined on models by setting the static `apiConfig` property. This is an object where you may configure model-level request configuration.
32
+
33
+
The following example configures a model with common `headers` and `baseURL` options:
24
34
25
35
```js
26
36
import { Model } from'@vuex-orm/core'
@@ -42,7 +52,11 @@ class User extends Model {
42
52
}
43
53
```
44
54
45
-
Finally, you can pass configuration when making the api call.
55
+
### Request Configuration
56
+
57
+
Options can be defined on a per-request basis. These options will inherit any global and model configurations which are subsequently passed on to the request.
58
+
59
+
The following example configures a request with common `headers` and `baseURL` options:
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.
68
+
Request configurations vary depending on the type of request being made. Please refer to the [Usage Guide](usage) to read more.
69
+
55
70
56
71
## Available Options
57
72
58
-
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.
73
+
In addition to [axios request options](https://github.com/axios/axios#request-config), the plugin can be configured with the following options:
74
+
75
+
### `dataKey`
59
76
60
-
### dataKey
77
+
-**Type**: `string`
78
+
-**Default**: `undefined`
61
79
62
-
-**`dataKey?: string | null`**
80
+
This option will inform the plugin of the resource key your elements may be nested under in the response body.
63
81
64
-
This option will define which key to look for when persisting response data. Let's say your response from the server looks like below.
82
+
For example, your response body may be nested under a resource key called `data`:
65
83
66
84
```js
67
85
{
@@ -72,52 +90,33 @@ All Axios configurations are available. For those, please refer to [the Axios do
72
90
}
73
91
}
74
92
```
75
-
76
-
In this case, data persistent to the store will probably fail, since actual data is inside the `data` key, but Vuex ORM Axios is going to insert whole object including `ok` property.
77
-
78
-
For these situations, you can use `dataKey` property to specify which key to look for data.
93
+
94
+
The following example sets the `dataKey` to `data` as this is the resource key which contains the required data for the model schema.
79
95
80
96
```js
81
97
User.api().get('/api/users', {
82
98
dataKey:'data'
83
99
})
84
100
```
85
101
86
-
With the above config, the data inside `data` key will be inserted to the store.
87
-
88
-
> **NOTE:** When `dataTransformer` key is set, this option will be ignored.
89
-
90
-
### dataTransformer
91
-
92
-
-**`dataTransformer?: ((response: AxiosResponse) => Record | Record[])`**
102
+
The plugin will pass all the data within the data object to Vuex ORM which can then be successfully persisted to the store.
93
103
94
-
This option will let you transform the response before persisting it to the store. Let's say your response from the server looks like below.
95
-
96
-
```js
97
-
{
98
-
ok:true,
99
-
record: {
100
-
id:1,
101
-
name:'John Doe'
102
-
}
103
-
}
104
-
```
104
+
::: warning
105
+
This option is ignored when using the `dataTransformer` option.
106
+
:::
105
107
106
-
You can use `dataTransform` property to specify how you want to transform the data. The whole Axios response will be passed as callback argument.
With the above config, the data inside `record` key will be inserted to the store.
113
+
This option will let you intercept and transform the response before persisting it to the store.
114
+
115
+
The method will receive a [Response](usage.md#handling-responses) object allowing you to access response properties such as response headers, as well as manipulate the data as you see fit.
117
116
118
-
It is very useful when you need to transform a given response to be handle by Vuex ORM. For instance, if you format your response with the [JSON:API specs](https://jsonapi.org/), you can transform your response with this callback.
117
+
Any method defined must return data to pass on to Vuex ORM.
119
118
120
-
You can always use object destructuring to get specific properties from the response object too.
119
+
You can also use object destructuring to get specific properties from the response object.
121
120
122
121
```js
123
122
User.api().get('/api/users', {
@@ -130,38 +129,39 @@ All Axios configurations are available. For those, please refer to [the Axios do
130
129
})
131
130
```
132
131
133
-
> **NOTE:** When `dataTransformer` key is set, `dataKey` option will be ignored.
132
+
::: warning
133
+
Using the `dataTransformer` option will ignore any `dataKey` option.
This option will determine whether to store the response data to the store or not. If you set this value to `false`, the response data will not be persisted to the store. In that case, the `entities` property at the Response object will become null.
140
+
-**Type**: `boolean`
141
+
-**Default**: `true`
140
142
141
-
```js
142
-
User.api().get('/api/users', {
143
-
save:false
144
-
})
145
-
```
143
+
This option will determine whether Vuex ORM should persist the response data to the store or not.
144
+
145
+
By setting this option to `false`, the response data will not be persisted and you will have to handle persistence alternatively. The `entities` property in the [Response](usage.md#handling-responses) object will also be `null` since it will no longer be persisting data automatically.
-**`delete?: string | number | (model: Model) => boolean`**
149
+
### `delete`
150
150
151
-
When this option is defined, the matching record will be deleted from the store after the api call. Usually, you need to set this when calling api to delete a record. When this option is set, the response data will not be persisted even if the `save` option is set to true.
151
+
-**Type**: `string | number | (model: Model) => boolean`
152
+
-**Default**: `undefined`
152
153
153
-
```js
154
-
User.api().delete('/api/users', {
155
-
delete:42
156
-
})
157
-
```
154
+
This option is primarily used with delete requests. It's argument signature is identical to the [Vuex ORM delete](https://vuex-orm.org/guide/data/deleting) method by which a primary key can be set as the value, or passing a predicate function. The corresponding record will be removed from the store after the request is made.
155
+
156
+
Setting this option will ignore any `save` options you may have set and therefore persistence is not possible when using this option.
158
157
159
-
Well, you may wonder having to manually specify what record to be deleted is a bit redundant. However, without this option, Vuex ORM Axios wouldn't know what records should be deleted because it can't rely on the response data.
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.
3
+
You can install Vuex ORM Axios via NPM, Yarn, or download it directly. This is a plugin for Vuex ORM, therefore you must ensure [Vuex ORM](https://vuex-orm.org/guide/prologue/installation)and [axios](https://github.com/axios/axios#installing) are installed.
[Unpkg.com](https://unpkg.com) provides NPM-based CDN links. The above link always points to the latest release on NPM. You can also use a specific version/tag via URLs like `https://unpkg.com/@vuex-orm/plugin-axios`.
21
+
[Unpkg.com](https://unpkg.com) provides NPM-based CDN links. Simply download and include with a script tag.
22
22
23
-
Include Vuex ORM Axios from an HTML script.
23
+
For development environments, testing and learning purposes, you can use the latest uncompressed version with:
In the `dist/` directory of the NPM package you will find many different builds. Each of them have their use depending on your build environment and may help to reduce bundle sizes.
0 commit comments