@abcum/ember-helpers v4.2.1

ember-helpers

A collection of helpers for Ember.js enabling advanced templating logic.

Usage

Installation

ember install @abcum/ember-helpers

Static helpers

Action helpers

The action helpers enable a variety of advanced actions.

Scroll helpers

The scroll helpers enable advanced document and block scroll positioning.

Sorter helpers

The sorter helpers enable advanced sorting logic to extend the sort-by helper.

Event helpers

The event helpers enable manipulation of browser events.

Router helpers

The router helpers enable a selection of router methods.

Object helpers

The array helpers enable advanced array logic and manipulation.

Array helpers

The array helpers enable advanced array logic and manipulation.

Promise helpers

The promise helpers enable working with models and promises.

Format helpers

The format helpers enable easy formatting of different units.

Input helpers

The input helpers enable complex regular expressions for easy input box validity checking.

Text helpers

The text helpers enable easy formatting of strings and text.

Logic helpers

The logic helpers enable logic operations in handlebars statements.

Math helpers

The math helpers enable maths calculations in handlebars statements.

Examples

Callback helpers

define

Defines the given property on the given object.

{{define this 'reversed' (reverse users)}}

run

Allows an action to be called with specified arguments.

{{#my-component onclick=(run (transition-to 'posts.post' post))}}
	View all posts
{{/my-component}}

Or you can specify that any additional curried arguments will be ignored.

{{#my-component onclick=(run (transition-to 'posts.post' post) curry=false)}}
	View all posts
{{/my-component}}

Action helpers

alert

Displays a window.alert message as a result of an action on a component.

{{#my-component onsave=(alert 'The blog post' blog.title 'has been saved.')}}
	Save
{{/my-component}}

call

Allows a method on the route to be called from a component.

{{#some-button clicked=(call "log" "Website")}}
	Log this error
{{/some-button}}

chain

Enables chaining of a sequence of actions together to form a larger action, passing the result of each action to the next action.

{{#my-component onclick=(action (chain (action 'addBasket') (action 'goToPayment')) model)}}
	Add to basket and pay
{{/my-component}}

If any action in the chain returns a promise, then the chain will wait for the promise to return, and the return value will be piped into the next action. If the Promise rejects, the rest of the chain will be aborted.

check

Checks if a value (as a result of an action) is truthy before running the defined action.

Useful when chaining actions together to prevent an action from running if the previous action returned false.

{{#my-component onclick=(action (chain (confirm 'Are you sure?') (check (action 'delete' model))))}}
	Delete this item
{{/my-component}}

confirm

Displays a window.confirm message as a result of an action on a component.

{{#my-component onclick=(confirm 'Are you sure you want to delete the blog post' blog.title '?')}}
	Delete
{{/my-component}}

console

Enables logging any passed or curried paramaters to the console, as a result of an action on a component.

{{#my-component onclick=(console 'clicked')}}
	Add to basket and pay
{{/my-component}}

Or you can specify which console logging type should be used to display the message. The different possible types are trace, debug, info, log, warn, error.

{{#my-component onclick=(console 'clicked' type='warn')}}
	Add to basket and pay
{{/my-component}}

debounce

Ensures an action is triggered only once during the specified time.

{{#my-component onclick=(debounce (action 'increment') 1000)}}
	+1
{{/my-component}}

link-invoke

Allows an action to be called while transitioning to another route with link-to.

{{#link-to "index" invoke="save"}}
	Save and go back
{{/link-to}}

Or you can use a closure action instead of a action name.

{{#link-to "index" invoke=(action "save")}}
	Save and go back
{{/link-to}}

Or you can add action parameters to be passed to the invoked action.

{{#link-to "index" invoke=(action "save" firstname lastname)}}
	Save and go back
{{/link-to}}

modify

Modifies the current selection of the given array with the curried item object.

{{#my-component onselect=(modify this model)}}
	Select
{{/my-component}}

export default Ember.Component.extend({
	click() {
		this.sendAction('onselect', item);
	}
});

Or toggle a selected item by passing the selected object and a toggle option.

export default Ember.Component.extend({
	click() {
		this.sendAction('onselect', item, { toggle:true, retain: true });
	}
});

Or select a range of items by passing the selected object and a range option.

export default Ember.Component.extend({
	click() {
		this.sendAction('onselect', item, { range:true, retain: true });
	}
});

Or to use a specific key on the controller within which the selection will be stored.

{{#my-component onselect=(modify this model key='selected')}}
	Select
{{/my-component}}

notify

Displays a notification as a result of an action on a component.

{{#my-component onsave=(notify "Thanks" "The blog post data has been saved.")}}
	Save
{{/my-component}}

prompt

Displays a window.prompt message as a result of an action on a component.

{{#my-component ask-name=(prompt 'What is your name?')}}

queue

Enables queuing of a sequence of actions together to form a larger action, passing the original arguments to each action.

{{#my-component onclick=(action (queue (action 'addBasket') (action 'goToPayment')) model)}}
	Add to basket and pay
{{/my-component}}

If any action in the queue returns a promise, then the queue will wait for the promise to return, before moving onto the next action. If the Promise rejects, the rest of the queue will be aborted.

toggle

Toggles the primary argument as a boolean value.

{{#my-component onclick=(toggle this 'isEnabled')}}
	{{#if isEnabled}}Disable{{else}}Enable{{/if}}
{{/my-component}}

Or you can toggle between specific values the primary argument as a boolean value.

{{#my-component onclick=(toggle this 'view' 'landscape' 'portrait')}}
	{{#if (eq view "landscape")}}Switch to portrait{{else}}Switch to landscape{{/if}}
{{/my-component}}

throttle

Waits for the specified time before running an action, discarding all events in the meantime.

{{#my-component onclick=(throttle (action 'increment') 1000)}}
	+1
{{/my-component}}

uncurry

Allows an action to be called with specified arguments, whilst ignoring any curried arguments.

{{#my-component onclick=(uncurry (transition-to 'posts.post' post))}}
	View all posts
{{/my-component}}

Scroll helpers

remember-scroll

Stores and sets the page scroll position of the page.

{{remember-scroll}}

Or remember the scroll position of individual pages with named keys.

{{remember-scroll key=(concat 'posts-' model.id)}}

scroll-block

Specify a scrollable area, and remember the scroll position across routes with named keys.

{{#scroll-block key=(concat 'post-comments-' model.id)}}
	Scrollable Area
{{/scroll-block}}

scroll-to

Scroll to a specified position from the top of the page.

{{#my-component onclick=(scroll-to position=1600)}}
	Scroll down
{{/my-component}}

Or scroll to a specific element on the page.

{{#my-component onclick=(scroll-to element='#footer')}}
	Scroll to footer
{{/my-component}}

Or animate the scrolling by specifying the number of milliseconds.

{{#my-component onclick=(scroll-to element='#footer' duration=2000)}}
	Scroll to footer slowly
{{/my-component}}

Sorter helpers

natural-sort

Sorts the given array using a natural sort order with the current locale.

{{#each (sort-by (natural-sort "name") people) as |person|}}
	{{!-- All people sorted by name ascending --}}
{{/each}}

You can also pass asc or desc suffixes to specify sort ordering.

{{#each (sort-by (natural-sort "name:desc") people) as |person|}}
	{{!-- All people sorted by name descending --}}
{{/each}}

Or you can specify that numeric collation should be used when sorting.

{{#each (sort-by (natural-sort "name" numeric=true) people) as |person|}}
	{{!-- All people sorted by name with numbers sorting correctly --}}
{{/each}}

Or you can specify that punctuation should be ignored when sorting.

{{#each (sort-by (natural-sort "name" ignorePunctuation=false) people) as |person|}}
	{{!-- All people sorted by name with punctuation ignored --}}
{{/each}}

Or you can specify which case should sort first. Possible values are lower, upper, or false (default).

{{#each (sort-by (natural-sort "name" caseFirst='upper') people) as |person|}}
	{{!-- All people sorted by name with upper case ordered first --}}
{{/each}}

Or you can specify the sensitivity of the locale sort algorithm. Possible values are case, accent, variant, or base (default).

{{#each (sort-by (natural-sort "name" sensitivity='case') people) as |person|}}
	{{!-- All people sorted by name with specifc sensitivity case ordering --}}
{{/each}}

Action helpers

drag-get

Gets metadata from the browser event dataTransfer object.

{{#my-component ondrop=(drag-get 'plain/text')}}
	Droppable Area
{{/my-component}}

Or you can use the application/json mime-type to get the data as an object.

{{#my-component ondrop=(drag-get 'application/json')}}
	Droppable Area
{{/my-component}}

Or use the chain helper to chain multiple actions together to complete the drag-and-drop functionality.

{{#my-component ondrop=(chain (prevent-default) (drag-get 'plain/text') (action 'droppedItem'))}}
	Droppable Area
{{/my-component}}

drag-set

Set custom metadata on the browser event dataTransfer object.

{{#my-component draggable="true" ondragstart=(drag-set 'plain/text' 'text data')}}
	Draggable Item
{{/my-component}}

Or you can use the application/json mime-type to set the data as an object.

{{#my-component draggable="true" ondragstart=(drag-set 'application/json' (hash id=1 type='card'))}}
	Draggable Item
{{/my-component}}

Or use the chain helper to chain multiple actions together to complete the drag-and-drop functionality.

{{#my-component draggable="true" ondragstart=(chain (drop-effect 'move') (effect-allowed 'move') (drag-set 'plain/text' 'text data'))}}
	Draggable Item
{{/my-component}}

drop-effect

Specifies the dropEffect property on the event dataTransfer object.

{{#my-component draggable="true" ondragstart=(drop-effect 'move')}}
	Draggable Item
{{/my-component}}

effect-allowed

Specifies the effectAllowed property on the event dataTransfer object.

{{#my-component draggable="true" ondragstart=(effect-allowed 'move')}}
	Draggable Item
{{/my-component}}

prevent-default

Runs the preventDefault method on the event handler object.

{{#my-component draggable="true" ondragstart=(prevent-default)}}
	Draggable Item
{{/my-component}}

stop-propagation

Runs the stopPropagation method on the event handler object.

{{#my-component draggable="true" ondragstart=(stop-propagation)}}
	Draggable Item
{{/my-component}}

Router helpers

is-active

Detects whether a specific route is active or not.

{{#if (is-active 'basket')}}
	My Basket
{{/if}}

history-back

Calls window.history.back() to reverse one position in the browser history.

{{my-component onkeypress=(history-back)}}

history-forward

Calls window.history.forward() to advance one position in the browser history.

{{my-component onkeypress=(history-forward)}}

open

Calls window.open() enabling opening a new browser tab or window from an action on a component.

{{my-component onkeypress=(open "https://github.com/" "abcum/ember-helpers" width=1200 height=600 center=true)}}

reload

Calls window.location.reload() enabling reloading the page, or changing the url from an action on a component.

{{my-component onkeypress=(reload)}}

transition-to

Allows the route to be changed from an action on a component, similar to link-to.

{{#my-component onclick=(transition-to "basket" sort=true)}}
	Go to basket
{{/my-component}}

Object helpers

group-by

Groups items in a given array by the given path.

{{#each-in (group-by "category" products) as |category products|}}
	- {{category}}
	{{#each products as |product|}}
		{{!-- Products grouped by category--}}
	{{/each}}
{{/each-in}}

match-by

Returns true if the given properties contain the given value.

{{input type="text" value=search}}

{{#if (match-by "firstname" "lastname" search person)}}
	{{!-- The firstname or lastname field contains search --}}
{{/if}}

You can also use an array containing the properties to search.

{{input type="text" value=search}}

{{input-select value=fields options=(array "firstname" "lastname")}}

{{#if (match-by fields search person)}}
	{{!-- The firstname or lastname field contains search --}}
{{/if}}

object-key

Extracts the property from the given object.

{{object-key "name" person}}

Array helpers

any-by

Checks whether the given property is true on any item in a given array.

{{#if (any-by "isAdult" people)}}
	{{!-- At least one of people has isAdult === true --}}
{{/if}}

Or if given property is equal to the given value on any item in a given array.

{{#if (any-by "isChild" false people)}}
	{{!-- At least one of people has isChild === false --}}
{{/if}}

append

Appends each given array to the previous given arrays, resulting in a single flat array.

{{#each (append user users) as |person|}}
	{{!-- Flat array of user and users --}}
{{/each}}

array

Lets you create arrays directly in the template.

{{#each (array 1 2 3 4 5) as |step|}}
	- Step {{step}} is ...
{{/each}}

compact

Removes empty values from the given array.

{{#each (compact people) as |person|}}
	{{!-- All with no null or undefined items --}}
{{/each}}

empty

Checks to see if an array is empty.

{{#if (empty people)}}
	No people exists...
{{/if}}

every-by

Checks whether the given property is true on every item in a given array.

{{#if (every-by "isAdult" people)}}
	{{!-- All people have isAdult === true --}}
{{/if}}

Or if given property is equal to the given value on every item in a given array.

{{#if (every-by "isChild" false people)}}
	{{!-- All people have isChild === false --}}
{{/if}}

filter

Returns the given array filtered by a callback.

{{#each (filter (action "checkAdult") people) as |adult|}}
	{{!-- All where checkAdult action is truthy --}}
{{/each}}

filter-by

Returns the given array filtered by a property.

{{#each (filter-by "isAdult" people) as |adult|}}
	{{!-- All where isAdult is truthy --}}
{{/each}}

Returns the given array filtered by a property.

{{#each (filter-by "isChild" false people) as |adult|}}
	{{!-- All where isChild is false --}}
{{/each}}

You can also pass an action as second argument.

{{#each (filter-by (gt 18 (object-key "age")) people) as |adult|}}
	{{!-- All where age is greater than 18 --}}
{{/each}}

find

Returns the first entry matching the given callback from the given array.

{{#with (find (action "checkAdult") people) as |adult|}}
	{{!-- The first item where isAdult is truthy. --}}
{{/with}}

find-by

Returns the first entry matching the given value from the given array.

{{#with (find-by "isAdult" people) as |adult|}}
	{{!-- The first item where isAdult is truthy. --}}
{{/with}}

Returns the first entry matching the given value from the given array.

{{#with (find-by "isChild" false people) as |adult|}}
	{{!-- The first item where isChild is false. --}}
{{/with}}

You can also pass an action as second argument.

{{#with (find-by (gt 18 (object-key "age")) people) as |adult|}}
	{{!-- The first item where age is greater than 18 --}}
{{/with}}

first

Returns the first object of the given array.

{{#with (first people) as |person|}}
	{{!-- The first person --}}
{{/with}}

flatten

Returns a flattened array from the given array.

let array = [ [1], [2], [3] ];

{{#each (flatten array) as |step|}}
	- Step {{step}} is ...
{{/each}}

includes

Checks to see if an array includes an object.

{{#if (includes selectedPerson people)}}
	selectedPerson exists within people...
{{/if}}

Or if an array includes an array of objects.

{{#if (includes selectedPeople people)}}
	selectedPeople exist within people...
{{/if}}

invoke

Calls a method on an object.

{{#each users as |user|}}
	<button {{action (invoke "save" user)}}>Save</button>
{{/each}}

Or on each item in an array.

<button {{action (invoke "save" users)}}>Save</button>

intersect

Returns an array of unique items which are present in all given arrays.

{{#each (intersect users admins) as |testers|}}
	{{!-- All who are in both users and admins --}}
{{/each}}

join

Concatenates the given array with an optional separator.

{{join (array "tag1" "tag2" "tag3")}} {{!-- "tag1 tag2 tag3" --}}

You can use an optional separator.

{{join ", " (array "tag1" "tag2" "tag3")}} {{!-- "tag1, tag2, tag3" --}}

last

Returns the last object of the given array.

{{#with (last people) as |person|}}
	{{!-- The last person --}}
{{/with}}

map

Returns the given array mapped to the given callback.

{{#each (map (action "getName") users) as |name|}}
	{{name}}
{{/each}}

map-by

Returns the given array mapped to the given property.

{{#each (map-by "name" users) as |name|}}
	{{name}}
{{/each}}

object-at

Returns the object at the given index of an array.

{{#with (object-at 1 people) as |person|}}
	{{!-- The 1st person --}}
{{/with}}

objects-at

Returns the object at the given indexes of an array.

{{#each (objects-at 1 3 5 people) as |person|}}
	{{!-- The 1st, 3rd, 5th people --}}
{{/each}}

omit

Returns the given array with the first count items omitted.

{{#each (omit 3 people) as |person|}}
	{{!-- All except the first 3 people --}}
{{/each}}

prepend

Prepends each given array to the previous given arrays, resulting in a single flat array.

{{#each (prepend user users) as |person|}}
	{{!-- Flat array of users and user --}}
{{/each}}

range

Creates an array whose contents is a range of numbers between min and max.

{{#each (range 10 20) as |step|}}
	...
{{/each}}

reject

Returns the given array filtered by a callback.

{{#each (reject (action "checkAdult") people) as |child|}}
	{{!-- All except where checkAdult action is truthy --}}
{{/each}}

reject-by

Returns the given array omitting those matching the property.

{{#each (reject-by "isAdult" people) as |child|}}
	{{!-- All except where isAdult is truthy --}}
{{/each}}

Returns the given array omitting those matching the property.

{{#each (reject-by "isChild" false people) as |child|}}
	{{!-- All except where isChild is false --}}
{{/each}}

You can also pass an action as second argument.

{{#each (reject-by (gt 18 (object-key "age")) people) as |child|}}
	{{!-- All except where age is greater than 18 --}}
{{/each}}

reverse

Rearranges the array in reverse order.

{{#each (reverse users) as |user|}}
	{{!-- All in reverse order --}}
{{/each}}

slice

Returns a slice of the given array.

{{#each (slice 0 5 people) as |person|}}
	{{!-- Only the first 5 people --}}
{{/each}}

search-by

Returns the given array where the given properties contain the given value.

{{input type="text" value=search}}

{{#each (search-by "firstname" "lastname" search people) as |person|}}
	{{!-- All where firstname or lastname contains search --}}
{{/each}}

You can also use an array containing the properties to search.

{{input type="text" value=search}}

{{input-select value=fields options=(array "firstname" "lastname")}}

{{#each (search-by fields search people) as |person|}}
	{{!-- All where firstname or lastname contains search --}}
{{/each}}

sort-by

Returns the given array sorted by the defined properties.

{{#each (sort-by "age:asc" people) as |person|}}
	{{!-- All people sorted by age ascending --}}
{{/each}}

You can also pass an action as second argument.

{{#each (sort-by (action "mySortAction") people) as |person|}}
	{{!-- All people sorted by the custom sorting action --}}
{{/each}}

sort-locale-by

Returns the given array sorted by the defined properties.

{{#each (sort-locale-by "name:asc" people) as |person|}}
	{{!-- All people sorted by name ascending --}}
{{/each}}

You can also pass asc or desc suffixes to specify sort ordering.

{{#each (sort-locale-by "name:desc" people) as |person|}}
	{{!-- All people sorted by name descending --}}
{{/each}}

Or you can specify that numeric collation should be used when sorting.

{{#each (sort-locale-by "age" people numeric=true) as |person|}}
	{{!-- All people sorted by age with numbers sorting correctly --}}
{{/each}}

Or you can specify that punctuation should be ignored when sorting.

{{#each (sort-locale-by "name" people ignorePunctuation=false) as |person|}}
	{{!-- All people sorted by name with punctuation ignored --}}
{{/each}}

Or you can specify which case should sort first. Possible values are lower, upper, or false (default).

{{#each (sort-locale-by "name" people caseFirst='upper') as |person|}}
	{{!-- All people sorted by name with upper case ordered first --}}
{{/each}}

Or you can specify the sensitivity of the locale sort algorithm. Possible values are case, accent, variant, or base (default).

{{#each (sort-locale-by "name" people sensitivity='case') as |person|}}
	{{!-- All people sorted by name with specifc sensitivity case ordering --}}
{{/each}}

split

Splits a string/strings on a character and returns an array.

{{#each (split "/" "app/styles/sub/main.js") as |directory|}}
	{{!-- Array of directories without / character --}}
{{/each}}

take

Returns the given array with the first count items only.

{{#each (take 3 people) as |person|}}
	{{!-- Only the first 3 people --}}
{{/each}}

union

Returns an array of unique items from all of the given arrays.

{{#each (union users admins) as |person|}}
	{{!-- Unique users and admins --}}
{{/each}}

uniq

Returns an array of unique items from all of the given arrays.

{{#each (uniq users admins) as |person|}}
	{{!-- Unique users and admins --}}
{{/each}}

uniq-by

Returns an array of unique items, compared using the given property, from the given array.

{{#each (uniq-by "email" users) as |person|}}
	{{!-- Unique users by email --}}
{{/each}}

w

Splits a string/strings on whitespace or turns multiple words into an array.

{{#each (w "First Second" "Third") as |step|}}
	- Step {{step}} is ...
{{/each}}

without

Returns the given array without the given item or items.

{{#each (without selectedusers users) as |user|}}
	{{!-- All users who are not in selectedusers --}}
{{/each}}

Promise helpers

await

Waits for a promise to resolve, and passes the promise contents to the helper.

If the author exists, but the promise has not yet been loaded, then the template will render anyway.

{{#if (await post.author)}}
	{{get (await post.author) 'fullname'}}
{{else}}
	This post has no author.
{{/if}}

is-fulfilled

Returns true when a promise is fulfilled.

{{#if (is-fulfilled post.author)}}
	The relationship promise has been fulfilled.
{{/if}}

is-loaded

Returns true if the ember-data model is currently loading.

{{#if (is-loaded posts)}}
	The route model has loaded.
{{/if}}

is-pending

Returns true if a promise is pending.

{{#if (is-pending post.author)}}
	The relationship promise is still pending.
{{/if}}

is-rejected

Returns true when a promise is rejected.

{{#if (is-rejected post.author)}}
	The relationship promise has been rejected.
{{/if}}

is-updating

Returns true if the ember-data model is currently updating.

{{#if (is-updating posts)}}
	The route model is currently updating.
{{/if}}

rsvp-all

Returns a new promise which is fulfilled when all the given promises have been fulfilled, or rejected if any of them become rejected. The returned value is an array of fulfillment values for the passed in promises.

{{#if (is-pending (rsvp-all model.tags model.comments))}}
	Tags and comments are loading...
{{/if}}

rsvp-hash

Returns a new promise which is fulfilled when all the given promises have been fulfilled, or rejected if any of them become rejected. The returned promise is fulfilled with a hash that has the same key names as the promises object argument.

{{#with (await (rsvp-hash tags=model.tags comments=model.comments)) as |data|}}
	There are {{data.tags.length}} tags and {{data.comments.length}} comments.
{{/with}}

rsvp-race

Returns a new promise which is fulfilled when the first promise to be fulfilled is resolved. The returned value is the value of the first fulfilled promise.

{{#with (await (rsvp-race model.tags model.comments)) as |data|}}
	We are displaying the data which resolved fastest.
{{/with}}

Development

• make install (install bower and ember-cli dependencies)
• make upgrade (upgrade ember-cli to the specified version)
• make tests (run all tests defined in the package)