ember-composable-helpers
Composable helpers for Ember that enables more declarative templating. These helpers can be composed together to form powerful ideas:
To install:
ember install ember-composable-helpers
Watch a free video overview presented by EmberMap:
Configuration
This addon performs optional tree-shaking – you can specify which helpers to whitelist or blacklist using only
or except
within your ember-cli-build.js
:
module.exports = function(defaults) {
var app = new EmberApp(defaults, {
'ember-composable-helpers': {
only: ['inc', 'dec', 'pipe'],
except: ['pipe', 'filter-by']
}
});
Both only
and except
can be safely used together (the addon computes the diff), although it's best if you only use one for your own sanity.
except: ['pipe'] // imports all helpers except `pipe`
only: ['pipe'] // imports only `pipe`
Argument ordering
This addon is built with composability in mind, and in order to faciliate that, the ordering of arguments is somewhat different then you might be used to.
For all non-unary helpers, the subject of the helper function will always be the last argument. This way the arguments are better readable if you compose together multiple helpers:
For action helpers, this will mean better currying semantics:
Available helpers
Usage
Action helpers
pipe
Pipes the return values of actions in a sequence of actions. This is useful to compose a pipeline of actions, so each action can do only one thing.
The pipe
helper is Promise-aware, meaning that if any action in the pipeline returns a Promise, its return value will be piped into the next action. If the Promise rejects, the rest of the pipeline will be aborted.
The pipe
helper can also be used directly as a closure action (using pipe-action
) when being passed into a Component, which provides an elegant syntax for composing actions:
compute
Calls an action as a template helper.
toggle
Toggles a boolean value.
toggle
can also be used directly as a closure action using toggle-action
:
toggle
also accepts optional values to rotate through:
optional
Allows for the passed in action to not exist.
String helpers
camelize
Camelizes a string using Ember.String.camelize
.
capitalize
Capitalizes a string using Ember.String.capitalize
.
classify
Classifies a string using Ember.String.classify
.
dasherize
Dasherizes a string using Ember.String.dasherize
.
truncate
Truncates a string with a characterLimit.
underscore
Capitalizes a string using Ember.String.underscore
.
html-safe
Mark a string as safe for unescaped output with Ember templates using Ember.String.htmlSafe
.
titleize
Titleizes a string
w
Splits a string on whitespace and/or turns multiple words into an array
or:
See also: Ember w
documentation
Array helpers
array
Similar to the hash
helper, this lets you compose arrays directly in the template:
map
Maps a callback on an array.
map-by
Maps an array on a property.
sort-by
Sort an array by given properties.
You can append :desc
to properties to sort in reverse order.
You can also pass a method as the first argument:
filter
Filters an array by a callback.
filter-by
Filters an array by a property.
If you omit the second argument it will test if the property is truthy.
You can also pass an action as second argument:
reject-by
The inverse of filter by.
If you omit the third argument it will test if the property is falsey.
You can also pass an action as third argument:
find-by
Returns the first entry matching the given value.
intersect
Creates an array of unique values that are included in all given arrays.
invoke
Invokes a method on an object, or on each object of an array.
union
Joins arrays to create an array of unique values. When applied to a single array, has the same behavior as uniq
.
take
Returns the first n
entries of a given array.
drop
Returns an array with the first n
entries omitted.
reduce
Reduce an array to a value.
The last argument is initial value. If you omit it, undefined will be used.
repeat
Repeats n
times. This can be useful for making an n-length arbitrary list for iterating upon (you can think of this form as a times helper, a la Ruby's 5.times { ... }
):
You can also give it a value to repeat:
reverse
Reverses the order of the array.
range
Generates a range of numbers between a min
and max
value.
It can also be set to inclusive
:
And works with a negative range:
join
Joins the given array with an optional separator into a string.
compact
Removes blank items from an array.
contains
Checks if a given value or sub-array is contained within an array.
append
Appends the given arrays and/or values into a single flat array.
chunk
Returns the given array split into sub-arrays the length of the given value.
without
Returns the given array without the given item(s).
shuffle
Shuffles an array with a randomizer function, or with Math.random
as a default. Your randomizer function should return a number between 0 and 1.
flatten
Flattens an array to a single dimension.
object-at
Returns the object at the given index of an array.
slice
Slices an array
next
Returns the next element in the array given the current element. Note: Accepts an optional boolean
parameter, useDeepEqual
, to flag whether a deep equal comparison should be performed.
has-next
Checks if the array has an element after the given element. Note: Accepts an optional boolean
parameter, useDeepEqual
, to flag whether a deep equal comparison should be performed.
previous
Returns the previous element in the array given the current element. Note: Accepts an optional boolean
parameter, useDeepEqual
, to flag whether a deep equal comparison should be performed.
has-previous
Checks if the array has an element before the given element. Note: Accepts an optional boolean
parameter, useDeepEqual
, to flag whether a deep equal comparison should be performed
Object helpers
group-by
Returns an object where the keys are the unique values of the given property, and the values are an array with all items of the array that have the same value of that property.
Math helpers
inc
Increments by 1
or step
.
dec
Decrements by 1
or step
.
See also:
Legal
DockYard, Inc © 2016