Skip to content

Commit 5492b38

Browse files
tmorehousetmorehouse
authored
feat(b-table): allow field definition properties filterByFormatted and sortByFormatted accept a formatter function reference (closes #3892) (#3898)
1 parent 03536a5 commit 5492b38

File tree

12 files changed

+149
-60
lines changed

12 files changed

+149
-60
lines changed

‎src/components/form-checkbox/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -479,8 +479,8 @@ Generally speaking, you'll want to use a particular state for specific types of
479479

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

486486
To apply one of the contextual state icons on `<b-form-checkbox>`, set the `state` prop to `false`

‎src/components/form-file/README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -226,12 +226,12 @@ Generally speaking, you'll want to use a particular state for specific types of
226226

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

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

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

‎src/components/form-group/README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -238,12 +238,12 @@ Generally speaking, you'll want to use a particular state for specific types of
238238

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

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

248248
Bootstrap v4 uses sibling CSS selectors of `:invalid` or `:valid` inputs to show the feedback text.
249249
Some form controls (such as checkboxes, radios, and file inputs, or inputs inside input-groups) are

‎src/components/form-input/README.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -210,12 +210,12 @@ Generally speaking, you'll want to use a particular state for specific types of
210210

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

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

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

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

317317
- `false`: Convey no errors detected (default)
318318
- `true` (or `'true'`): Convey that the value has failed validation.

‎src/components/form-radio/README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -360,12 +360,12 @@ Generally speaking, you'll want to use a particular state for specific types of
360360

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

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

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

‎src/components/form-select/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -385,8 +385,8 @@ Generally speaking, you'll want to use a particular state for specific types of
385385

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

392392
To apply one of the contextual state icons on `<b-form-select>`, set the `state` prop to `false`

‎src/components/form-textarea/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -186,8 +186,8 @@ Generally speaking, you'll want to use a particular state for specific types of
186186

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

193193
To apply one of the contextual state icons on `<b-form-textarea>`, set the `state` prop to `false`

‎src/components/form/README.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -337,11 +337,10 @@ of three contextual states:
337337

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

344-
345344
Refer to the
346345
[Bootstrap v4 Form Validation Documentation](https://getbootstrap.com/docs/4.3/components/forms/#validation)
347346
for details on the new Bootstrap v4 validation states.

‎src/components/table/README.md

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -243,16 +243,16 @@ The following field properties are recognized:
243243
| `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. |
244244
| `sortable` | Boolean | Enable sorting on this column. Refer to the [Sorting](#sorting) Section for more details. |
245245
| `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. |
246-
| `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. |
247-
| `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. |
246+
| `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. |
247+
| `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. |
248248
| `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`. |
249249
| `thClass` | String or Array | Class name (or array of class names) to add to this field's `<thead>`/`<tfoot>` heading `<th>` cell. |
250250
| `thStyle` | Object | JavaScript object representing CSS styles you would like to apply to the table `<thead>`/`<tfoot>` field `<th>`. |
251251
| `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). |
252252
| `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`. |
253253
| `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`. |
254254
| `isRowHeader` | Boolean | When set to `true`, the field's item data cell will be rendered with `<th>` rather than the default of `<td>`. |
255-
| `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 |
255+
| `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 |
256256

257257
**Notes:**
258258

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

18481851
The default sort-compare routine works similar to the following. Note the fourth argument (sorting
18491852
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
19501953
- Normally, `<b-table>` filters based on the stringified record data. If the field has a `formatter`
19511954
function specified, you can optionally filter based on the result of the formatter by setting the
19521955
[field definition property](#field-definition-reference) `filterByFormatted` to `true`. If the
1953-
field does not have a formatter function, this option is ignored.
1956+
field does not have a formatter function, this option is ignored. You can optionally pass a
1957+
formatter function _reference_, to be used for filtering only, to the field definition property
1958+
`filterByFormatted`.
19541959

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

0 commit comments

Comments
 (0)