@billow/js-helpers
v2.1.6
Published
A useful set of JS helpers for Billow's Vue apps. Includes a component mixin, a bunch of filters, and string utilities.
Downloads
17
Readme
JS Helpers, by Billow
A useful set of JS helpers for Billow's Vue apps. Includes a component mixin, a bunch of filters, and string utilities.
Installation
npm install @billow/js-helpers
Query String mixin
Used for managing tabs through window history, the query-string mixin is obtainable from helpers.mixins.queryString
. In your component:
import { mixins } from '@billow/js-helpers'
export default {
mixins: [
mixins.queryString,
],
}
To set a tab, call this.setTab(tabName)
. The active tab can be obtained from this.activeTab
.
Note that this mixin relies on a Vuex store being injected, and interacts with a namespaced module called
app
. This module must have a mutator namedsetTab
which accepts the name of a tab and mutates it in state, as well as a getter namedtab
, which simply returns the name of the tab from wherever it lives in state.
If you'd prefer, you can also import the mixin directly:
import queryStringMixin from '@billow/js-helpers/src/mixins/query-string'
FormData utility
If you need to leverage the FormData API to submit multipart form data via an XHR request, you can make use of this utility, which merges an object's keys and values (often from state) together, whilst retaining integrity of data that would often be lost without passing through this API, such as a File.
import { utilities } from '@billow/js-helpers'
// Somewhere in a store module, like an action:
let payload = utilities.formData({
...state.userProfile,
picture: state.profilePicture
})
// Or if your file (a picture, in this example) is in the same state key:
let payload = utilities.formData(state.userProfile)
If you'd prefer, you can also import the utility directly:
import makeFormData from '@billow/js-helpers/src/utilities/form-data'
String utility
A simple utility that currently exports a format
helper, which assists in formatting a string using named keys. A filter is also available to leverage this utility.
import { utilities } from '@billow/js-helpers'
utilities.string.format('{key} equals :value', {
key: this.generateKey(),
value: this.value,
})
If you'd prefer, you can also import the utility directly:
import { format } from '@billow/js-helpers/src/utilities/string'
Filters
import { filters } from '@billow/js-helpers'
// Install the filters
Vue.use(filters)
The available filters are listed below in alphabetical order with a method signature (if available) and at least one example.
You can access filters using {{ var | filter([args]) }}
in your component template, or this.$options.filters.filter(var[, args])
in your JS.
💡 Some filter-arguments are swappable, meaning that
{{ a | b(c) }}
and{{ c | b(a) }}
would produce the same result.
asAccounting
Arguments: (currency = 'R', precision = 2, thousandsSeparator = ',', precisionSeparator = '.', format = '%s %v')
Examples:
2000 | asAccounting // R 2,000.00
2000 | asAccounting('$') // $ 2,000.00
15982.115 | asAccounting('R', 3) // R 15,982.115
2000 | asAccounting('R', 2, ' ') // R 2 000.00
2000 | asAccounting('€', 2, '.', ',') // € 2.000,00
2000 | asAccounting('CAD', 2, ',', '.', '%v %s') // 2,000.00 CAD
asCurrency
Signature: (currency = 'R ', locale = 'en-GB')
Examples:
2000 | asCurrency // R 2,000.00
2000 | asCurrency('$') // $ 2,000.00
123456.789 | asCurrency('₹', 'en-IN') // ₹ 1,23,456.789
asMoney
Signature: (fractionDigits = 2, maximumFractionDigits = 2, locale = 'en-GB')
Examples:
2000 | asMoney // 2,000.00
2000.211 | asMoney(3) // 2,000.211
2000.21109 | asMoney(3, 5) // 2,000.21109
12345678.7891 | asMoney(3, 5, 'en-IN') // 1,23,456.7891
asPlain
Convert HTML to plain text.
<template>
<div>{{ body | asPlain }}</div>
</template>
<!-- In laoreet exercitation? Accusantium, pede? Nascetur, [...] -->
export default {
data: () => ({
body: '<p>In laoreet exercitation? Accusantium, pede? <br><br> Nascetur, aspernatur pretium feugiat, nullam rerum suscipit pulvinar dignissimos nulla sint, rerum dolorum fames hac.</p>'
})
}
date
Signature: (format = 'Y-MM-DD')
Examples
'2018-05-24 12:00:00' | date // 2018-05-24
'2018-05-24 17:00:00' | date('ddd, hA') // Thur, 5PM
filesize
Signature: (base = 2, exponent = -1)
Example:
38889823 | filesize // 37.09 MB
38889823 | filesize(2, 3) // 0.04 GB
format
Format a string using named keys. Arguments are swappable.
Signature: (format|object)
, where the argument is the format string and the input is the object from which data is obtained, or vice-versa.
Examples:
user | format(':name has role of :role') // Mike has a role of member
':name has role of :role' | format(user) // Mike has a role of member
user = {
name: 'Mike',
role: 'member'
}
fromNow
Signature: (suffix = true)
Examples:
'2018-09-10' | fromNow // in 4 months
'2018-05-24 07:24:00' | fromNow // 4 minutes ago
'2018-05-24 07:24:00' | fromNow(false) // 4 minutes
log
Logs the input to the console.
Example:
'I’m in the console' | log
nl2br
Convert line breaks to HTML breaks
Example:
<div v-html="$options.filters.nl2br(multilineString)"></div>
or
Similar to using the logical-or (a || b
, where a
is falsy for example), only or
uses a stricter truthy-check, unless loose
is true.
Signature: (fallback, loose = false)
Examples:
undefined | or('n/a')
null | or('n/a')
'' | or('n/a')
0 | or('n/a') // 0
0 | or('n/a', true) // n/a
false | or('n/a') // false
false | or('n/a', true) // n/a
ordinal
Example:
2 | ordinal // 2nd
4 | ordinal // 4th
plural
Pluralise a word when the input is a number greater than 1. Arguments are swappable.
Signature: (count|singular)
, where the argument is the singular word and the input is the count, or vice-versa.
Examples:
1 | plural('apple') // apple
2 | plural('apple') // apples
1 | plural('fish') // fish
2 | plural('fish') // fish
'apple' | plural(1)
'apple' | plural(2)
'fish' | plural(1)
'fish' | plural(2)
replace
Signature: (search, replace)
Examples:
'foo bar' | replace('foo', 'boo') // boo bar
'A123E' | replace(/\d/, '*') // A*23E
toFixed
Signature: (precision = 2)
Example:
"2.983726" | toFixed // 2.98
truncate
Signature: (length = 20, omission = '…', separator = /,? +/)
Examples:
'Error gravida dis phasellus deleniti, nostrud.' | truncate
// Error gravida dis…
'Error gravida dis phasellus deleniti, nostrud.' | truncate('[…]')
// Error gravida dis[…]
ucfirst
Example:
'billow' | ucfirst // Billow
ucwords
Example:
'do you use vue?' | ucwords // Do You Use Vue?