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 is tested and compatible with 1.13.1+ ember versions. See travis CI build and report here

Note that the 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.

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
• bower install

Running dummy demo app

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

Running Tests

• npm test (Runs ember try:each to test your addon against multiple Ember versions)
• ember test
• ember test --server

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/.