feat(table) busy state self-handling (bootstrap-vue#881)

mosinve · tmorehouse · commit 7e1c6415a32c · 2017-08-19T22:14:11.000-03:00
* WIP feat(table) busy state self-handling

* WIP feat(table) busy state self-handling

* some fixes

* [table] doc tweaks

:)

* docs update

* Update README.md

* docs minor typo fix
diff --git a/docs/components/table/README.md b/docs/components/table/README.md
@@ -18,7 +18,6 @@ custom rendering, events, and asynchronous data.
       </b-form-fieldset>
     </div>
   </div>
-
   <div class="row my-1">
     <div class="col-sm-8">
       <b-pagination :total-rows="totalRows" :per-page="perPage" v-model="currentPage" />
@@ -150,15 +149,15 @@ Supported field properties:
 | `thStyle` | Object | JavaScript object representing CSS styles you would like to apply to the table field `<th>`
 | `formatter` | String or Function | A formatter callback function, can be used instead of slots for real table fields (i.e. fields, that have corresponding data at items array)
 
-Notes:
- - Field properties, if not present, default to null unless otherwise stated above.
- - `thClass` and `tdClass` will not work with classes that are defined in scoped CSS
- - For information on the syntax supported by `thStyle`, see
+>***Notes:***
+ >- *Field properties, if not present, default to null unless otherwise stated above.*
+ >- *`thClass` and `tdClass` will not work with classes that are defined in scoped CSS*
+ >- *For information on the syntax supported by `thStyle`, see
 [Class and Style Bindings](https://vuejs.org/v2/guide/class-and-style.html#Binding-Inline-Styles)
-in the Vue.js guide.
- - Any additional properties added to the field objects will be left intact - so you can access
-them via the named scoped slots for custom data, header, and footer rendering.
-- by design, slots and formatter are **mutually exclusive**. Ie. if formatter defined at field props, then slot will not be used even if it defined for this field.
+in the Vue.js guide.*
+ >- *Any additional properties added to the field objects will be left intact - so you can access
+them via the named scoped slots for custom data, header, and footer rendering.*
+>- *by design, slots and formatter are **mutually exclusive**. Ie. if formatter defined at field props, then slot will not be used even if it defined for this field.*
 
 ### Items (record data)
 `items` are real table data record objects in array format. Example format:
@@ -193,8 +192,8 @@ Supported optional item record modifier properties (make sure your field keys do
 | `_cellVariants` | Object | Bootstrap contextual state applied to individual cells. Keyed by field (Supported values: `active`, `success`, `info`, `warning`, `danger`)
 | `state` | String | **deprecated** in favour of `_rowVariant`
 
-**Note** `state` is deprecated. The property `_rowVariant`, if present in
-the record, will be prefered.
+>***Note:** `state` is deprecated. The property `_rowVariant`, if present in
+the record, will be prefered.*
 
 `items` can also be a reference to a *provider* function, which returns an `Array` of items data.
 Provider functions can also be asynchronous:
@@ -229,7 +228,7 @@ See the **"Using Items Provider functions"** section below for more details.
 Custom rendering for each data field in a row is possible using either 
 [scoped slots](http://vuejs.org/v2/guide/components.html#Scoped-Slots) or formatter callback function.
 
-####Slots
+#### Slots
 If you want to add an extra field which does not exist in the records,
 just add it to the `fields` array.  Example:
 
@@ -299,10 +298,10 @@ The slot's scope variable (`data` in the above sample) will have the following p
 | `item` | Object | The entire record (i.e. `items[index]`) for this row
 | `index` | Number | The row number (zero based)
 
-**Note** that `index` will not always be the actual row's index number, as it is
+>***Note:** `index` will not always be the actual row's index number, as it is
 computed after pagination and filtering have been applied to the original
 table data. The `index` value will refer to the **displayed row number**. This
-number will align with the indexes from the optional `v-model` bound variable.
+number will align with the indexes from the optional `v-model` bound variable.*
 
 When placing inputs, buttons, selects or links within a data cell scoped slot,
 be sure to add a `@click.stop` handler (which can be empty) to prevent the
@@ -398,7 +397,7 @@ the original `items` array (except when `items` is set to a provider function).
 Deleteing a record from the v-model will **not** remove the record from the
 original items array.
 
-**Note:** Do not bind any value directly to the `value` prop. Use the `v-model` binding.
+>***Note:** Do not bind any value directly to the `value` prop. Use the `v-model` binding.*
 
 ### Filtering
 Filtering, when used, is aplied to the original items array data, and hence it is not
@@ -464,8 +463,8 @@ if (typeof a[key] === 'number' && typeof b[key] === 'number') {
 As mentioned under the `items` prop section, it is possible to use a function to provide
 the row data (items), by specifying a function reference via the `items` prop.
 
-**Note:** The `items-provider` prop has been deprecated in favour of providing a function
-reference to the `items` prop. A console warning will be issued if `items-provider` is used.
+>***Note:** The `items-provider` prop has been deprecated in favour of providing a function
+reference to the `items` prop. A console warning will be issued if `items-provider` is used.*
 
 The provider function is called with the following signature:
 
@@ -508,7 +507,7 @@ function myProvider(ctx, callback) {
         let items = data.items;
         // Provide the array of items to the callabck
         callback(items);
-    })
+    }).catch(error => {callback([])})
 
     // Must return null or undefined
     return null;
@@ -525,17 +524,23 @@ function myProvider(ctx) {
         // Pluck the array of items off our axios response
         let items = data.items;
         // Must return an array of items
-        return(items);
+        return(items || []);
     });
 }
 ```
 
-`<b-table>` provides a `busy` prop that will flag the table as busy, which you can
-set to `true` just before your async fetch, and then set it to `false` once you have
-your data, and just before you send it to the table for display. Example:
+`<b-table>` automatically tracks/controls it's `busy` state, however it provides
+a `busy` prop that can be used either to override inner `busy`state, or to monitor
+b-table's current busy state in your application using the 2-way `.sync` modifier.
+
+>***Note:** in order to allow `<b-table>` fully track it's `busy` state, custom items
+provider function should handle errors from data sources and return an empty
+array to `<b-table>`*
+
+Example:
 
 ```html
-<b-table id="my-table" :busy="isBusy" :items="myProvider" :fields="fields" ....>
+<b-table id="my-table" :busy.sync="isBusy" :items="myProvider" :fields="fields" ....>
 </b-table>
 ```
 ```js
@@ -546,18 +551,27 @@ data () {
 }
 methods: {
     myProvider(ctx) {
-        this.isBusy = true
+        // Here we don't set isBusy prop, so state will be handled by table itself
         let promise = axios.get('/some/url');
 
         return promise.then((data) => {
             const items = data.items;
+            // Here we override the state, setting isBusy to false 
             this.isBusy = false
             return(items);
+        }).catch(error => {
+            // Returning an empty array, allows table to correctly handle state in case of error
+            return []
         });
     }
  }
 ```
 
+>***Note:** If you manually place the table in the `busy` state, the items provider will
+__not__ be called/refreshed until the `busy` state has been set to `false`. All click
+related events and sort-changed events will __not__ be emiited when in the `busy` state.*
+
+#### Provider Sorting, Paging, Filtering
 By default, the items provider function is responsible for **all paging, filtering, and sorting**
 of the data, before passing it to `b-table` for display.
 
diff --git a/lib/components/table.vue b/lib/components/table.vue
@@ -1,6 +1,6 @@
 <template>
     <table :id="id || null"
-           :aria-busy="busy ? 'true' : 'false'"
+           :aria-busy="computedBusy ? 'true' : 'false'"
            :class="tableClass"
     >
         <thead :class="headClass">
@@ -126,13 +126,14 @@
                 localSortDesc: this.sortDesc || false,
                 localItems: [],
                 // Note: filteredItems only used to determine if # of items changed
-                filteredItems: []
+                filteredItems: [],
+                localBusy: this.busy
             };
         },
         props: {
             id: {
                 type: String,
-                default: ''
+                'default': ''
             },
             items: {
                 type: [Array, Function],
@@ -147,84 +148,84 @@
             },
             sortBy: {
                 type: String,
-                default: null
+                'default': null
             },
             sortDesc: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             apiUrl: {
                 type: String,
-                default: ''
+                'default': ''
             },
             fields: {
                 type: Object,
-                default: {}
+                'default': {}
             },
             striped: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             bordered: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             inverse: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             hover: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             small: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             responsive: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             headVariant: {
                 type: String,
-                default: ''
+                'default': ''
             },
             footVariant: {
                 type: String,
-                default: ''
+                'default': ''
             },
             perPage: {
                 type: Number,
-                default: null
+                'default': null
             },
             currentPage: {
                 type: Number,
-                default: 1
+                'default': 1
             },
             filter: {
                 type: [String, RegExp, Function],
-                default: null
+                'default': null
             },
             sortCompare: {
                 type: Function,
-                default: null
+                'default': null
             },
             itemsProvider: {
                 // Deprecated in favour of items
                 type: Function,
-                default: null
+                'default': null
             },
             noProviderPaging: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             noProviderSorting: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             noProviderFiltering: {
                 type: Boolean,
-                default: false
+                'default': false
             },
             busy: {
                 type: Boolean,
@@ -314,11 +315,18 @@
                 if (oldVal !== newVal && !this.noProviderFiltering) {
                     this._providerUpdate();
                 }
+            },
+            localBusy(newVal, oldVal) {
+                if (newVal !== oldVal) {
+                    this.$emit('update:busy', newVal);
+                }
+
             }
         },
         mounted() {
             this.localSortBy = this.sortBy;
             this.localSortDesc = this.sortDesc;
+            this.localBusy = this.busy;
             if (this.hasProvider) {
                 this._providerUpdate();
             }
@@ -428,8 +436,10 @@
 
                 // Update the value model with the filtered/sorted/paginated data set
                 this.$emit('input', items);
-
                 return items;
+            },
+            computedBusy() {
+                return this.busy || this.localBusy;
             }
         },
         methods: {
@@ -463,7 +473,7 @@
                 ];
             },
             rowClicked(e, item, index) {
-                if (this.busy) {
+                if (this.computedBusy) {
                     // If table is busy (via provider) then don't propagate
                     e.preventDefault();
                     e.stopPropagation();
@@ -472,7 +482,7 @@
                 this.$emit('row-clicked', item, index);
             },
             rowDblClicked(e, item, index) {
-                if (this.busy) {
+                if (this.computedBusy) {
                     // If table is busy (via provider) then don't propagate
                     e.preventDefault();
                     e.stopPropagation();
@@ -481,7 +491,7 @@
                 this.$emit('row-dblclicked', item, index);
             },
             rowHovered(e, item, index) {
-                if (this.busy) {
+                if (this.computedBusy) {
                     // If table is busy (via provider) then don't propagate
                     e.preventDefault();
                     e.stopPropagation();
@@ -490,7 +500,7 @@
                 this.$emit('row-hovered', item, index);
             },
             headClicked(e, field, key) {
-                if (this.busy) {
+                if (this.computedBusy) {
                     // If table is busy (via provider) then don't propagate
                     e.preventDefault();
                     e.stopPropagation();
@@ -527,16 +537,18 @@
             },
             _providerSetLocal(items) {
                 this.localItems = (items && items.length > 0) ? items.slice() : [];
+                this.localBusy = false;
                 this.$emit('refreshed');
                 this.emitOnRoot('table::refreshed', this.id);
             },
             _providerUpdate() {
                 // Refresh the provider items
-                if (this.busy || !this.hasProvider) {
+                if (this.computedBusy || !this.hasProvider) {
                     // Don't refresh remote data if we are 'busy' or if no provider
                     return;
                 }
 
+                this.localBusy = true;
                 // Call provider function with context and optional callback
                 const data = this.items(this.context, this._providerSetLocal);
 
