Skip to content

Commit b0c6c9f

Browse files
marshallswainmarshallswain
authored
Merge pull request #524 from fratzinger/docs-mixins
docs: seperate mixins
2 parents 7b4de7d + 14123ac commit b0c6c9f

File tree

1 file changed

+158
-28
lines changed

1 file changed

+158
-28
lines changed

‎docs/mixins.md

Lines changed: 158 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -52,51 +52,181 @@ In the above example, any records returned from the server will automatically sh
5252

5353
Notice in the above example that using the mixin automatically makes the `serverTasks` available in the template. The mixins automatically setup a few properties in the viewModel based on the camelCased name of the service. You can also provide a `name` attribute to override the defaults:
5454

55-
## Options
55+
## makeFindMixin
5656

57-
### for `makeFindMixin` and `makeGetMixin`
57+
### Options
5858

59-
The `makeFindMixin` and `makeGetMixin` utilities share the following options in common. Unique options are found further down.
60-
61-
- **service {String}** - **required** the service path. This must match a service that has already been registered with FeathersVuex.
62-
- **name {String}** - The name to use in all of the dynamically-generated property names. See the section about Dynamically Generated Props
63-
- **items {String}** - The attribute name to use for the records.
64-
65-
- **params {String|Function}** - One of two possible params attributes. (The other is `fetchParams`) When only `params` is provided, it will be used for both the `find` getter and the `find` action. When using server-side pagination, use `fetchParams` for server communciation and the `params` prop for pulling data from the local store. If the params is `null` or `undefined`, the query against both the API will be skipped. The find getter will return an empty array. **Default {String}: `${camelCasedService}Params`** (So, by default, it will attempt to use the property on the component called serviceName + "Params")
59+
- `service {String|Function}` - **required** the service path. This must match a service that has already been registered with FeathersVuex.
60+
- **{String}** - The service namespace
61+
- **{Function}** - Any provided function will become a computed property in the component and will be used to determine its value.
62+
- `name {String}` - The name to use in all of the dynamically-generated property names. See the section about Dynamically Generated Props
63+
- `items {String}` - The attribute name to use for the records.
64+
- `params {String|Function}` - One of two possible params attributes. (The other is `fetchParams`) When only `params` is provided, it will be used for both the `find` getter and the `find` action. When using server-side pagination, use `fetchParams` for server communciation and the `params` prop for pulling data from the local store. If the params is `null` or `undefined`, the query against both the API will be skipped. The find getter will return an empty array. **Default {String}: `${camelCasedService}Params`** (So, by default, it will attempt to use the property on the component called serviceName + "Params")
6665
- **{String}** - The name of the attribute in the current component which holds or returns the query object.
6766
- **{Function}** - A provided function will become a computed property in the current component.
67+
- `watch {String|Array<String>}` - specifies the attributes of the `params` or `fetchParams` to watch. When a watched prop changes, a new request will be made to the API server. Pass 'params' to watch the entire params object. Pass 'params.query.name' to watch the 'name' property of the query. Watch is turned off by default, meaning only one initial request is made. **Default {String}: `${camelCasedService}Params`**
68+
- **{Boolean}** - If `true`: `[${camelCasedService}Params]` will be watched, else `[]`
69+
- **{String}** - The name of the component's prop to use as the value. Transformed to an `Array<String>`
70+
- **{Array<String>}** - Names of the component's prop
71+
- `fetchParams {String|Function}` - when provided, the `fetchParams` serves as the params for the API server request. When `fetchParams` is used, the `param` attribute will be used against the service's local Vuex store. **Default: undefined**
72+
- **{String}** - The name of the attribute in the current component which holds or returns the params object.
73+
- **{Function}** - A provided function will become a computed property in the current component.
74+
- `queryWhen {Boolean|String|Function}` - the query to the server will only be made when this evaluates to true. **Default: true**
75+
- **{Boolean}** - As a boolean, the value provided determines whether this is on or off.
76+
- **{String}** - The name of the component's prop to use as the value.
77+
- **{Function}** - Any provided function will become a method in the component and will receive the current params object as an argument.
78+
- `local {Boolean|String|Function}` - when true, will only use the `params` prop to pull data from the local Vuex store. It will disable queries to the API server. The value of `local` will override `queryWhen`. **Default:false**
79+
- **{Boolean}** - As a boolean, the value provided determines whether this is on or off.
80+
- **{String}** - The name of the component's prop to use as the value.
81+
- **{Function}** - Any provided function will become a computed property in the component and will be used to determine its value.
82+
- `qid {String}` - The "query identifier" ("qid", for short) is used for storing pagination data in the Vuex store. See the service module docs to see what you'll find inside. The `qid` and its accompanying pagination data from the store will eventually be used for cacheing and preventing duplicate queries to the API.
83+
84+
### Injected Properties
85+
86+
With `makeFindMixin` the following properties will be injected into your component and can become handy to use manually. Since the names of the mixin are basically dynamically generated by the `service` and `name` props you pass. Here the general names to understand what's going on under the hood:
87+
88+
#### Dynamically Generated Props:
89+
```vue
90+
<script>
91+
// general
92+
export default {
93+
data: {
94+
[IS_FIND_PENDING]: false, // `isFind${capitalized}Pending`
95+
[HAVE_ITEMS_BEEN_REQUESTED_ONCE]: false, // `have${capitalized}BeenRequestedOnce`
96+
[HAVE_ITEMS_LOADED_ONCE]: false, // `have${capitalized}LoadedOnce`
97+
[MOST_RECENT_QUERY]: null, // `${prefix}LatestQuery`
98+
[ERROR]: null // ${prefix}Error
99+
},
100+
computed: {
101+
[PAGINATION]() {/* ... */} // `${prefix}PaginationData`
102+
[ITEMS]() {/* ... */}, // `${items}` || `${name}` || `${camelCasedPluralService}`
103+
[ITEMS_FETCHED]() {/* ... */} // `${items}Fetched` || `${name}Fetched` || `${camelCasedPluralService}Fetched`
104+
[FIND_GETTER]() {/* ... */} // `find${capitalized}InStore``
105+
},
106+
methods: {
107+
[`${FIND_ACTION}DebouncedProxy`](params) {/* ... */} // `get${capitalized}`
108+
[FIND_ACTION](params) {/* ... */}
109+
}
110+
}
111+
```
112+
#### Example with `service: 'server-tasks`
113+
```vue
114+
<script>
115+
// example with 'server-tasks' service
116+
export default {
117+
mixins: [
118+
makeGetMixin({
119+
service: 'server-tasks' // depending on service
120+
})
121+
],
122+
data: {
123+
isFindServerTasksPending: false,
124+
haveServerTasksBeenRequestedOnce: false,
125+
haveServerTasksLoadedOnce: false,
126+
serverTasksError: null
127+
},
128+
computed: {
129+
serverTasksPaginationData() { /* ... */ }
130+
serverTasks() { /* ... */ },
131+
serverTasksFetched() { /* .. */ },
132+
findServerTasksInStore(params) { /* ... */ },
133+
},
134+
methods: {
135+
findServerTasksDebouncedProxy(params) { /* ... */ },
136+
findServerTasks(params) { /* ... */ }
137+
}
138+
}
139+
</script>
140+
141+
```
68142

69-
- **watch {String|Array}** - specifies the attributes of the `params` or `fetchParams` to watch. When a watched prop changes, a new request will be made to the API server. Pass 'params' to watch the entire params object. Pass 'params.query.name' to watch the 'name' property of the query. Watch is turned off by default, meaning only one initial request is made. **Default {String}: `${camelCasedService}Params`**
143+
## makeGetMixin
70144

71-
- **fetchParams {String|Function}** - when provided, the `fetchParams` serves as the params for the API server request. When `fetchParams` is used, the `param` attribute will be used against the service's local Vuex store. **Default: undefined**
145+
### Options
146+
147+
- `id {String|Function}` - when performing a `get` request, serves as the id for the request. This is automatically watched, so if the `id` changes, an API request will be made and the data will be updated. If `undefined` or `null`, no request will be made. **Default: undefined**
148+
- **{String}** - The name of the component's prop to use as the value.
149+
- **{Function}** - Any provided function will become a computed property in the component and will be used to determine its value.
150+
- `service {String|Function}` - **required** the service path. This must match a service that has already been registered with FeathersVuex.
151+
- **{String}** - The service namespace
152+
- **{Function}** - Any provided function will become a computed property in the component and will be used to determine its value.
153+
- `name {String}` - The name to use in all of the dynamically-generated property names. See the section about Dynamically Generated Props
154+
- `item {String}` - The attribute name to use for the record.
155+
- `params {String|Function}` - One of two possible params attributes. (The other is `fetchParams`) When only `params` is provided, it will be used for both the `find` getter and the `find` action. When using server-side pagination, use `fetchParams` for server communciation and the `params` prop for pulling data from the local store. If the params is `null` or `undefined`, the query against both the API will be skipped. The find getter will return an empty array. **Default {String}: `${camelCasedSingularizedService}Params`** (So, by default, it will attempt to use the property on the component called serviceName + "Params")
156+
- **{String}** - The name of the attribute in the current component which holds or returns the query object.
157+
- **{Function}** - A provided function will become a computed property in the current component.
158+
- `watch {Boolean|String|Array<String>}` - specifies the attributes of the `params` or `fetchParams` to watch. When a watched prop changes, a new request will be made to the API server. Pass 'params' to watch the entire params object. Pass 'params.query.name' to watch the 'name' property of the query. Watch is turned off by default, meaning only one initial request is made. **Default {Array}: `[]`**
159+
- **{Boolean}** - If `true`: `[${camelCasedService}Params]` will be watched, else `[]`
160+
- **{String}** - The name of the component's prop to use as the value. Transformed to an `Array<String>`
161+
- **{Array<String>}** - Names of the component's prop
162+
- `fetchParams {String|Function}` - when provided, the `fetchParams` serves as the params for the API server request. When `fetchParams` is used, the `param` attribute will be used against the service's local Vuex store. **Default: undefined**
72163
- **{String}** - The name of the attribute in the current component which holds or returns the params object.
73164
- **{Function}** - A provided function will become a computed property in the current component.
74165

75-
- **queryWhen {Boolean|String|Function}** - the query to the server will only be made when this evaluates to true. **Default: true**
166+
- `queryWhen {Boolean|String|Function}` - the query to the server will only be made when this evaluates to true. **Default: true**
76167
- **{Boolean}** - As a boolean, the value provided determines whether this is on or off.
77168
- **{String}** - The name of the component's prop to use as the value.
78169
- **{Function}** - Any provided function will become a method in the component and will receive the current params object as an argument.
79170

80-
- **local {Boolean|String|Function}** - when true, will only use the `params` prop to pull data from the local Vuex store. It will disable queries to the API server. The value of `local` will override `queryWhen`. **Default:false**
171+
- `local {Boolean|String|Function}` - when true, will only use the `params` prop to pull data from the local Vuex store. It will disable queries to the API server. The value of `local` will override `queryWhen`. **Default:false**
81172
- **{Boolean}** - As a boolean, the value provided determines whether this is on or off.
82173
- **{String}** - The name of the component's prop to use as the value.
83174
- **{Function}** - Any provided function will become a computed property in the component and will be used to determine its value.
84175

85-
### Options for only `makeFindMixin`
176+
### Injected Properties
86177

87-
The `makeFindMixin` has these unique options:
178+
With `makeGetMixin` the following properties will be injected into your component and can become handy to use manually. Since the names of the mixin are basically dynamically generated by the `service` and `name` props you pass. Here the general names to understand what's going on under the hood:
88179

89-
- **qid {String}** - The "query identifier" ("qid", for short) is used for storing pagination data in the Vuex store. See the service module docs to see what you'll find inside. The `qid` and its accompanying pagination data from the store will eventually be used for cacheing and preventing duplicate queries to the API.
90-
91-
### Options for only `makeGetMixin`
180+
#### Dynamically Generated Props:
181+
```vue
182+
<script>
183+
export default {
184+
data: {
185+
[IS_GET_Pending]: false, // `isGet${capitalized}Pending`
186+
[HAS_ITEM_BEEN_REQUESTED_ONCE]: false, // `has${capitalized}BeenRequestedOnce`
187+
[HAS_ITEM_LOADED_ONCE]: false, // `has${capitalized}LoadedOnce`
188+
[ERROR]: null // `${prefix}Error`
189+
},
190+
computed: {
191+
[ITEM]() { /* ... */ }, // `${item}` || `${name}` || ${camelCasedSingularService}`
192+
[GET_GETTER]() { /* ... */ } // `get${capitalized}FromStore`
193+
},
194+
methods: {
195+
[GET_ACTION]() { /* ... */ } // `get${capitalized}`
196+
}
197+
}
198+
```
199+
#### Example with `service: 'server-tasks`
200+
```vue
201+
<script>
202+
// example
203+
export default {
204+
mixins: [
205+
makeGetMixin({
206+
service: 'server-tasks' // depending on service
207+
})
208+
],
209+
data: {
210+
isGetServerTaskPending: false,
211+
hasServerTaskBeenRequestedOnce: false,
212+
hasServerTaskLoadedOnce: false,
213+
serverTaskError: null
214+
},
215+
computed: {
216+
serverTask() { /* ... */ },
217+
getServerTaskFromStore(params) { /* ... */ },
218+
},
219+
methods: {
220+
getServerTask(params) { /* ... */ }
221+
}
222+
}
223+
</script>
92224
93-
The `makeGetMixin` has these unique options:
225+
```
94226

95-
- **id {String|Function}** - when performing a `get` request, serves as the id for the request. This is automatically watched, so if the `id` changes, an API request will be made and the data will be updated. If `undefined` or `null`, no request will be made. **Default: undefined**
96-
- **{String}** - The name of the component's prop to use as the value.
97-
- **{Function}** - Any provided function will become a computed property in the component and will be used to determine its value.
227+
## Patterns & Examples
98228

99-
## Dynamically Generated Props
229+
### Dynamically Generated Props
100230

101231
Based on what options you provide to each mixin, some dynamically-generated props will be added to the current component. Note that the example below only shows the return values from the computes, not the functions.
102232

@@ -166,7 +296,7 @@ makeFindMixin({ service: 'videos', name: 'myVideos' }) = {
166296
}
167297
```
168298

169-
## Using a dynamic service
299+
### Using a dynamic service
170300

171301
It's possible to change the service name on the fly. To do this, pass a function (which becomes a computed property) that returns another string property from the viewModel. Below is an example of how to set that up. The `serviceName` attribute is set to `"videos"`, initially. The `setTimeout` in the `created` method changes the value to `"users"` after three seconds. When the serviceName changes, the users service is queried automatically. The `items` property will then update to be the newly fetched users instead of the video records that it contained before. The `items` option is used to rename the items to something more generic.
172302

@@ -233,7 +363,7 @@ const mixedInDataFromAboveExample = {
233363
}
234364
```
235365

236-
## Pagination with fall-through cacheing
366+
### Pagination with fall-through cacheing
237367

238368
The `makeFindMixin` in `[email protected]` features a great new, high performance, fall-through cacheing feature, which only uses a single query! Read the service module documentation for details of how it works under the hood. It really makes easy work of high-performance pagination. To use the pagination, provide `$limit` and `$skip` attributes in `params.query`. This is exactly the same way you would normally do with any FeathersJS query. So this is completely transparent to how you'd normally do it.
239369

@@ -290,7 +420,7 @@ export default {
290420

291421
In the above example, since we've enabled the `watch` attribute on the makeFindMixin, every time the params change, the query will run again. `feathers-vuex` will keep track of the queries and the pages that are visited, noting which records are returned on each page. When a page is revisited, the data in the store will *immedately* display to the user. The query will (by default) go out to the API server, and data will be updated in the background when the response arrives.
292422

293-
## Debouncing requests
423+
### Debouncing requests
294424

295425
What happens when a query with a watcher is attached to an attribute that might change rapidly? A lot of API requests can get sent in succession. If too many are sent, some of them will start to fail (a.k.a. bounce). The `makeFindMixin` has a built-in utility for debouncing requests. Enabling it makes it so requests only are sent after a specific amount of time has passed. To enable it, pass a `debounce` attribute in the `params`, as shown in the next example.
296426

@@ -366,7 +496,7 @@ We also added a `$regex` search to the params. This is a MongoDB feature, which
366496

367497
Feel free to make a PR for using something else that could be useful to the community! We love those!
368498

369-
## Enabling live lists with pagination
499+
### Enabling live lists with pagination
370500

371501
The new fall-through cacheing pagination does not currently support live sorting of lists. This means that when a new record arrives from the database, it doesn't automatically get sorted into the correct page and shuffle the other records around it. The lists will update as the user navigates to previous/next pages. Coming up with a solution for this will be a top priority after 2.x ships. In the meantime, here are some alternatives.
372502

@@ -487,7 +617,7 @@ export default {
487617
</template>
488618
```
489619

490-
## Debugging the makeFindMixin
620+
### Debugging the makeFindMixin
491621

492622
**Important: For the built in pagination features to work, you must not directly manipulate the `context.params` object in any hooks.**
493623

0 commit comments

Comments
 (0)