ember-array-contains-helper

Ember template helper allowing to test if an array contains a particular element.

{{array-contains model 'value' property='title'}}

This helper allows to test the presence of a literal, a full object or a specific property/value of an object inside a given array. Objects can be native or Ember objects.

Observing

This addon installs observers on the provided array to listen any external change made on it. It includes any addition/removal of an item and, if a property is specified, any change of the property of any array element.

Documentation

The documentation is available here.

Samples & Demo

• A dummy demo application containing syntax samples runs here
• The source code of this demo can be found here

Compatibility

• This helper basically works in 1.13.0 ember version but the changes on the array (add/remove/change property) will not rerun the helper. This is probably due to this bug.
• Versions before 2.x are tested and compatible with ember versions from 1.13.1 to 2.12.
• After 2.x, tests are only run against the two last LTS ember versions, release, beta and canary. See ember-try config for details

See travis CI build and report here for current tests and compatibility details.

Troubleshooting

Before its version 2.x, this addon came with a polyfill (ember-runtime-enumerable-includes-polyfill) emulating the native EcmaScript method includes in case you wanted to run it within an environment that did not support this method.

Since its version 2.x, the polyfill is not included by default and this addon relies on the fact that it is run in an environment supporting the includes method. Errors will occur if it is not the case.

If you want to use this addon in an older browser or environment that does not support includes, you must then now explicitely add the polyfill as a regular dependency: yarn add ember-runtime-enumerable-includes-polyfill.

Installation

• ember install ember-array-contains-helper

Usage

{{array-contains <array> <value> [property='<property>']}}

Where:

• <array> is the array to search into. Should be a valid not null array.
• <value> is the value which is supposed to be contained in the arrray. Could be an object or a literal, null or undefined.
• <property> is an option: if set, the search is done on the presence of an object containing a property <property> with the value <value>. If not, the search is done of the presence of the full <value> (object or literal)

This helper could be:

• used standalone:

  {{array-contains model 'value' property='title'}}

• or, more often, combined with the if helper:

  {{if (array-contains model 'value' property='title') 'something' 'something else'}}

Depending on the given parameters, the test is made on

• the presence of a literal:

// routes/application.js
 
import Ember from 'ember';
export default Ember.Route.extend({
  model () {
    return ['Akira', 'Blacksad', 'CalvinAndHobbes'];
  }
});

{{!-- templates/application.hbs --}}
 
{{array-contains model 'Akira'}}

• the presence of the object itself:

// routes/application.js
 
import Ember from 'ember';
import Comic from '../models/comic';
 
let blackSad = Comic.create({
  title: 'Blacksad'
});
 
let calvinAndHobbes = Comic.create({
  title: 'Calvin and Hobbes'
});
 
let akira = Comic.create({
  title: 'Akira'
});
 
export default Ember.Route.extend({
  model () {
    return [akira, blacksad, calvinAndHobbes];
  },
  
  setupController (controller, model) {
    controller.set('calvinAndHobbes', calvinAndHobbes);
    this._super(controller, model);
  },
});

{{!-- templates/application.hbs --}}
   
{{array-contains model calvinAndHobbes}}

• the presence of an object containing a specific property with a specific value using the option property:

// routes/application.js
 
import Ember from 'ember';
 
export default Ember.Route.extend({
  model () {
    return this.store.findAll('comic');
  }
});

{{!-- templates/application.hbs --}}
   
{{array-contains model 'Blacksad' property='title'}}

null and undefined

null and undefined are considered acceptable values for 'value' parameter.

• until ember 2.9, null and undefined are both coerced to null by the templating engine. The following expressions are therefore both leading to check for the presence of a null value inside the array:

  {{array-contains collection null}}
  {{array-contains collection undefined}}

• ember 2.10 (glimmer) changed this behaviour. undefined are then preserved and not coerced to null anymore.

It could eventually break some apps relying on the initial behaviour but it has been considered as a fix since the first behaviour was accidental. See this issue for details.

Changelog

Changelog can be found here

Contributing

Thank you!!!

• Open an Issue for discussion first if you're unsure a feature/fix is wanted.
• Branch off of master (Use descriptive branch names)
• Follow DockYard Ember.js Style Guide
• if needed, add or update documentation following YUIDoc syntax
• Test your features / fixes
• Use Angular-Style Commits. Use correct type, short subject and motivated body.
• PR against master
• Linting & tests must pass, coverage and codeclimate should be preserved

Development

Installation

• git clone https://github.com/bmeurant/ember-array-contains-helper
• cd ember-array-contains-helper
• npm install

Running dummy demo app

• npm install
• ember server
• Visit your app at http://localhost:4200.

Linting

• npm run lint:js
• npm run lint:js -- --fix

Running Tests

• ember test – Runs the test suite on the current Ember version
• ember test --server – Runs the test suite in "watch mode"
• npm test – Runs ember try:each to test your addon against multiple Ember versions

Building

• ember build

Generating documentation

This addon uses YUIDoc via ember-cli-yuidoc. yuidoc-ember-cli-theme makes it pretty. Docs generation is enabled in development mode via ember build or ember serve with or without --docs auto refresh option. It can also be explicitely generated with ember ember-cli-yuidoc command.

For more information on using ember-cli, visit https://www.ember-cli.com/.