Skip to content
Permalink
Browse files

feat(b-table): allow field definition properties `filterByFormatted` …

…and `sortByFormatted` accept a formatter function reference (closes #3892) (#3898)
  • Loading branch information...
tmorehouse committed Aug 16, 2019
1 parent 03536a5 commit 5492b38a71d9a36314f801a40c026f0ef108cd05
@@ -479,8 +479,8 @@ Generally speaking, you'll want to use a particular state for specific types of

- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
must fill in this field properly to submit the form.
- `true` (denotes valid state) is ideal for situations when you have per-field validation
throughout a form and want to encourage a user through the rest of the fields.
- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
a form and want to encourage a user through the rest of the fields.
- `null` Displays no validation state (neither valid nor invalid)

To apply one of the contextual state icons on `<b-form-checkbox>`, set the `state` prop to `false`
@@ -226,12 +226,12 @@ Generally speaking, you'll want to use a particular state for specific types of

- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
must fill in this field properly to submit the form.
- `true` (denotes valid state) is ideal for situations when you have per-field validation
throughout a form and want to encourage a user through the rest of the fields.
- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
a form and want to encourage a user through the rest of the fields.
- `null` Displays no validation state (neither valid nor invalid)

To apply one of the contextual state icons on `<b-form-file>`, set the `state` prop to `false`
(for invalid), `true` (for valid), or `null` (no validation state).
To apply one of the contextual state icons on `<b-form-file>`, set the `state` prop to `false` (for
invalid), `true` (for valid), or `null` (no validation state).

**Note:** Contextual states are **not** supported when in button mode.

@@ -238,12 +238,12 @@ Generally speaking, you'll want to use a particular state for specific types of

- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
must fill in this field properly to submit the form.
- `true` (denotes valid state) is ideal for situations when you have per-field validation
throughout a form and want to encourage a user through the rest of the fields.
- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
a form and want to encourage a user through the rest of the fields.
- `null` Displays no validation state (neither valid nor invalid)

To apply one of the contextual state icons on `<b-form-group>`, set the `state` prop to `false`
(for invalid), `true` (for valid), or `null` (no validation state).
To apply one of the contextual state icons on `<b-form-group>`, set the `state` prop to `false` (for
invalid), `true` (for valid), or `null` (no validation state).

Bootstrap v4 uses sibling CSS selectors of `:invalid` or `:valid` inputs to show the feedback text.
Some form controls (such as checkboxes, radios, and file inputs, or inputs inside input-groups) are
@@ -210,12 +210,12 @@ Generally speaking, you'll want to use a particular state for specific types of

- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
must fill in this field properly to submit the form.
- `true` (denotes valid state) is ideal for situations when you have per-field validation
throughout a form and want to encourage a user through the rest of the fields.
- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
a form and want to encourage a user through the rest of the fields.
- `null` Displays no validation state (neither valid nor invalid)

To apply one of the contextual state icons on `<b-form-input>`, set the `state` prop to `false`
(for invalid), `true` (for valid), or `null` (no validation state).
To apply one of the contextual state icons on `<b-form-input>`, set the `state` prop to `false` (for
invalid), `true` (for valid), or `null` (no validation state).

```html
<b-container fluid>
@@ -311,8 +311,8 @@ text block.
Specifically for assistive technologies, invalid form controls can also be assigned an
`aria-invalid="true"` attribute.

When `<b-form-input>` has an invalid contextual state (i.e. state is `false`) you may also want
to set the `<b-form-input>` prop `aria-invalid` to `true`, or to one of the supported values:
When `<b-form-input>` has an invalid contextual state (i.e. state is `false`) you may also want to
set the `<b-form-input>` prop `aria-invalid` to `true`, or to one of the supported values:

- `false`: Convey no errors detected (default)
- `true` (or `'true'`): Convey that the value has failed validation.
@@ -360,12 +360,12 @@ Generally speaking, you'll want to use a particular state for specific types of

- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
must fill in this field properly to submit the form.
- `true` (denotes valid state) is ideal for situations when you have per-field validation
throughout a form and want to encourage a user through the rest of the fields.
- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
a form and want to encourage a user through the rest of the fields.
- `null` Displays no validation state (neither valid nor invalid)

To apply one of the contextual state icons on `<b-form-radio>`, set the `state` prop to `false`
(for invalid), `true` (for valid), or `null` (no validation state).
To apply one of the contextual state icons on `<b-form-radio>`, set the `state` prop to `false` (for
invalid), `true` (for valid), or `null` (no validation state).

**Note:** Contextual state is not supported for radios rendered in buttons mode.

@@ -385,8 +385,8 @@ Generally speaking, you'll want to use a particular state for specific types of

- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
must fill in this field properly to submit the form.
- `true` (denotes valid state) is ideal for situations when you have per-field validation
throughout a form and want to encourage a user through the rest of the fields.
- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
a form and want to encourage a user through the rest of the fields.
- `null` Displays no validation state (neither valid nor invalid)

To apply one of the contextual state icons on `<b-form-select>`, set the `state` prop to `false`
@@ -186,8 +186,8 @@ Generally speaking, you'll want to use a particular state for specific types of

- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
must fill in this field properly to submit the form.
- `true` (denotes valid state) is ideal for situations when you have per-field validation
throughout a form and want to encourage a user through the rest of the fields.
- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
a form and want to encourage a user through the rest of the fields.
- `null` Displays no validation state (neither valid nor invalid)

To apply one of the contextual state icons on `<b-form-textarea>`, set the `state` prop to `false`
@@ -337,11 +337,10 @@ of three contextual states:

- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
must fill in this field properly to submit the form.
- `true` (denotes valid state) is ideal for situations when you have per-field validation
throughout a form and want to encourage a user through the rest of the fields.
- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
a form and want to encourage a user through the rest of the fields.
- `null` Displays no validation state (neither valid nor invalid)


Refer to the
[Bootstrap v4 Form Validation Documentation](https://getbootstrap.com/docs/4.3/components/forms/#validation)
for details on the new Bootstrap v4 validation states.
@@ -243,16 +243,16 @@ The following field properties are recognized:
| `formatter` | String or Function | A formatter callback function or name of a method in your component, can be used instead of (or in conjunction with) scoped field slots. Refer to [Custom Data Rendering](#custom-data-rendering) for more details. |
| `sortable` | Boolean | Enable sorting on this column. Refer to the [Sorting](#sorting) Section for more details. |
| `sortDirection` | String | Set the initial sort direction on this column when it becomes sorted. Refer to the [Change initial sort direction](#Change-initial-sort-direction) Section for more details. |
| `sortByFormatted` | Boolean | <span class="badge badge-info small">NEW in 2.0.0-rc.28</span> Sort the column by the result of the field's `formatter` callback function. Default is `false`. Has no effect if the field does not have a `formatter`. Refer to the [Sorting](#sorting) Section for more details. |
| `filterByFormatted` | Boolean | <span class="badge badge-info small">NEW in 2.0.0-rc.28</span> Filter the column by the result of the field's `formatter` callback function. Default is `false`. Has no effect if the field does not have a `formatter`. Refer to the [Filtering](#filtering) section for more details. |
| `sortByFormatted` | Boolean or Function | Sort the column by the result of the field's `formatter` callback function when set to `true`. Default is `false`. Boolean has no effect if the field does not have a `formatter`. Optionally accepts a formatter function _reference_ to format the value before sorting. Refer to the [Sorting](#sorting) Section for more details. |
| `filterByFormatted` | Boolean or Function | Filter the column by the result of the field's `formatter` callback function when set to `true`. Default is `false`. Boolean has no effect if the field does not have a `formatter`. Optionally accepts a formatter function _reference_ to format the value before filtering. Refer to the [Filtering](#filtering) section for more details. |
| `tdClass` | String or Array or Function | Class name (or array of class names) to add to `<tbody>` data `<td>` cells in the column. If custom classes per cell are required, a callback function can be specified instead. The function will be called as `tdClass( value, key, item )` and it may return an `Array` or `String`. |
| `thClass` | String or Array | Class name (or array of class names) to add to this field's `<thead>`/`<tfoot>` heading `<th>` cell. |
| `thStyle` | Object | JavaScript object representing CSS styles you would like to apply to the table `<thead>`/`<tfoot>` field `<th>`. |
| `variant` | String | Apply contextual class to all the `<th>` **and** `<td>` in the column - `active`, `success`, `info`, `warning`, `danger`. These variants map to classes `thead-${variant}` (in the header), `table-${variant}` (in the body), or `bg-${variant}` (when the prop `dark` is set). |
| `tdAttr` | Object or Function | JavaScript object representing additional attributes to apply to the `<tbody>` field `<td>` cell. If custom attributes per cell are required, a callback function can be specified instead. The function will be called as `tdAttr( value, key, item )` and it may return an `Object`. |
| `thAttr` | Object or Function | JavaScript object representing additional attributes to apply to the field's `<thead>`/`<tfoot>` heading `<th>` cell. If the field's `isRowHeader` is set to `true`, the attributes will also apply to the `<tbody>` field `<th>` cell. If custom attributes per cell are required, a callback function can be specified instead. The function will be called as `thAttr( value, key, item, type )` and it may return an `Object`. |
| `isRowHeader` | Boolean | When set to `true`, the field's item data cell will be rendered with `<th>` rather than the default of `<td>`. |
| `stickyColumn` | Boolean | <span class="badge badge-info small">NEW in 2.0.0-rc.28</span> When set to `true`, and the table in in [responsive](#responsive-tables) mode or has [sticky headers](#sticky-headers), will cause the column to become fixed to the left when the table's horizontal scrollbar is scrolled. See [Sticky columns](#sticky-columns) for more details |
| `stickyColumn` | Boolean | When set to `true`, and the table in in [responsive](#responsive-tables) mode or has [sticky headers](#sticky-headers), will cause the column to become fixed to the left when the table's horizontal scrollbar is scrolled. See [Sticky columns](#sticky-columns) for more details |

**Notes:**

@@ -1729,9 +1729,10 @@ if it is an object and then sorted.
data: scoped slots are used only for _presentation only_, and do not affect the underlying data.
- Fields that have a [`formatter` function](#formatter-callback) (virtual field or regular field)
can be sorted by the value returned via the formatter function if the
[field](#field-definition-reference) property `sortByFormatted` is set to `true`. The default is
`false` which will sort by the original field value. This is only applicable for the built-in
sort-compare routine.
[field](#field-definition-reference) property `sortByFormatted` is set to `true`. Optionally you
can pass a formatter function reference to `sortByFormatted` to format the value before sorting.
The default is `false` which will sort by the original field value. This is only applicable for
the built-in sort-compare routine.
- By default, the internal sorting routine will sort `null`, `undefined`, or empty string values
first (less than any other values). To sort so that `null`, `undefined` or empty string values
appear last (greater than any other value), set the `sort-null-last` prop to `true`.
@@ -1818,11 +1819,13 @@ optional:
- the third argument is the field `key` being sorted on (`sortBy`)
- the fourth argument (`sortDesc`) is the order `<b-table>` will be displaying the records (`true`
for descending, `false` for ascending)
- the fifth argument is a reference to the field's [formatter function](#formatter-callback) (or
`undefined` if no field formatter). You will need to call this method to get the formatted field
value: `valA = formatter(a[key], key, a)` and `valB = formatter(b[key], key, b)`, if you need to
sort by the formatted value. This will be `undefined` if the field's `sortByFormatted` property is
not `true`
- the fifth argument is a reference to the field's [formatter function](#formatter-callback) or the
field's `filterByFormatted` value if it is a function reference. If not formatter is found this
value will be `undefined`. You will need to call this method to get the formatted field value:
`valA = formatter(a[key], key, a)` and `valB = formatter(b[key], key, b)`, if you need to sort by
the formatted value. This will be `undefined` if the field's `sortByFormatted` property is not
`true` or is not a formatter function _reference_, or the fields formatter function cannot be
found.
- the sixth argument is the value of the `sort-compare-options` prop (default is
`{ numeric: true }`)
- the seventh argument is the value of the `sort-compare-locale` prop (default is `undefined`)
@@ -1843,7 +1846,7 @@ Your custom sort-compare routine can also return `null` or `false`, to fall back
sort-compare routine_ for the particular `key`. You can use this feature (i.e. by returning `null`)
to have your custom sort-compare routine handle _only_ certain fields (keys) such as the special
case of virtual (scoped slot) columns, and have the internal (built in) sort-compare handle all
other fields.
_other_ fields.

The default sort-compare routine works similar to the following. Note the fourth argument (sorting
direction) is **not** used in the sort comparison:
@@ -1950,7 +1953,9 @@ There are several options for controlling what data the filter is applied agains
- Normally, `<b-table>` filters based on the stringified record data. If the field has a `formatter`
function specified, you can optionally filter based on the result of the formatter by setting the
[field definition property](#field-definition-reference) `filterByFormatted` to `true`. If the
field does not have a formatter function, this option is ignored.
field does not have a formatter function, this option is ignored. You can optionally pass a
formatter function _reference_, to be used for filtering only, to the field definition property
`filterByFormatted`.

The props `filter-ignored-fields` and `filter-included-fields`, and the field definition property
`filterByFormatted` have no effect when using a [custom filter function](#custom-filter-function),

0 comments on commit 5492b38

Please sign in to comment.
You can’t perform that action at this time.