README.md

ember-cli-flash

Simple, highly configurable flash messages for ember-cli.

This ember-cli addon adds a simple flash message service and component to your app. The service is injected into all Controllers, Routes, Views and Components by default (you can change this), or lazily injected with Ember.inject.service.

Installation

You can install either with ember install:

For Ember CLI >= 0.2.3:

ember install ember-cli-flash

For Ember CLI < 0.2.3:

ember install:addon ember-cli-flash

Compatibility

This addon is tested against the release, beta and canary channels.

Usage

Usage is very simple. From within the factories you injected to (defaults to Controller, Route, View and Component):

Convenience methods (Bootstrap / Foundation alerts)

You can quickly add flash messages using these methods from the service:

Bootstrap

• .success
• .warning
• .info
• .danger

Foundation

• .success
• .warning
• .info
• .alert
• .secondary

These will add the appropriate classes to the flash message component for styling in Bootstrap or Foundation. For example:

// Bootstrap: the flash message component will have 'alert alert-success' classes
// Foundation: the flash message component will have 'alert-box success' classes
Ember.get(this, 'flashMessages').success('Success!');

Custom messages

If the convenience methods don't fit your needs, you can add custom messages with add:

Ember.get(this, 'flashMessages').add({
  message: 'Custom message'
});

Custom messages API

You can also pass in options to custom messages:

Ember.get(this, 'flashMessages').add({
  message            : 'I like alpacas',
  type               : 'alpaca'
  timeout            : 500,
  priority           : 200,
  sticky             : true,
  showProgress       : true,
  extendedTimeout    : 500,
});

Ember.get(this, 'flashMessages').success('This is amazing', {
  timeout      : 100,
  priority     : 100,
  sticky       : false,
  showProgress : true
});

• message: string

  Required. The message that the flash message displays.

• type?: string

  Default: info

  This is mainly used for styling. The flash message's type is set as a class name on the rendered component, together with a prefix. The rendered class name depends on the message type that was passed into the component.

• timeout?: number

  Default: 3000

  Number of milliseconds before a flash message is automatically removed.

• priority?: number

  Default: 100

  Higher priority messages appear before low priority messages. The best practise is to use priority values in multiples of 100 (100 being the lowest priority).

• sticky?: boolean

  Default: false

  By default, flash messages disappear after a certain amount of time. To disable this and make flash messages permanent (they can still be dismissed by click), set sticky to true.

• showProgress?: boolean

  Default: false

  To show a progress bar in the flash message, set this to true.

• extendedTimeout?: number

  Default: 0

  Number of milliseconds before a flash message is removed to add the class 'exiting' to the element. This can be used to animate the removal of messages with a transition.

Arbitrary options

You can also add arbitrary options to messages:

Ember.get(this, 'flashMessages').success('Cool story bro', {
  someOption : 'hello'
});

Ember.get(this, 'flashMessages').add({
  message  : 'hello',
  type     : 'foo',
  template : 'some-template',
  context  : customContext
});

Example use case

For example, this allows the template that ultimately renders the flash to be as rich as it needs to be:

{{#each flashMessages.queue as |flash|}}
  {{#flash-message flash=flash as |component flash|}}
    {{#if flash.template}}
      {{render flash.template flash.context}}
    {{else}}
      <h6>{{component.flashType}}</h6>
      <p>{{flash.message}}</p>
    {{/if}}
  {{/flash-message}}
{{/each}}

Service defaults

In config/environment.js, you can override service defaults in the flashMessageDefaults object:

module.exports = function(environment) {
  var ENV = {
    flashMessageDefaults: {
      timeout            : 5000,
      priority           : 200,
      sticky             : true,
      showProgress       : true,
      type               : 'alpaca',
      types              : [ 'alpaca', 'notice', 'foobar' ],
      injectionFactories : [ 'route', 'controller', 'view', 'component' ]
    }
  }
}

See the options section for detailed option information. This lets you override defaults for various options – most notably, you can specify exactly what types you need, which means in the above example, you can do Ember.get('flashMessages').{alpaca,notice,foobar}.

Injection factories

The key injectionFactories lets you choose which factories the service injects itself into. If you only need to access the flash message service from inside controllers, you can do so by changing the injectionFactories prop to [ 'controller' ]. Note that this will also work with any valid registry name on the container, e.g. [ 'component:foo', 'controller:bar', 'route:baz' ].

Lazy service injection

If you're using Ember 1.10.0 or higher, you can opt to inject the service manually on any Ember.Object registered in the container:

export default {
  flashMessages: Ember.inject.service()
}

Clearing all messages on screen

It's best practise to use flash messages sparingly, only when you need to notify the user of something. If you're sending too many messages, and need a way for your users to clear all messages from screen, you can use this method:

Ember.get(this, 'flashMessages').clearMessages();

Promises

You can take advantage of Promises, and their .then and .catch methods. To add a flash message after saving a model (or when it fails):

actions: {
  saveFoo() {
    const flashMessages = Ember.get(this, 'flashMessages');

    Ember.get(this, 'model').save()
    .then((res) => {
      flashMessages.success('Successfully saved!');
      doSomething(res);
    })
    .catch((err) => {
      flashMessages.danger('Something went wrong!');
      handleError(err);
    });
  }
}

Custom flash message component

If the provided component isn't to your liking, you can easily create your own. All you need to do is pass in the flash object to that component:

{{#each flashMessages.queue as |flash|}}
  {{custom-component flash=flash}}
{{/each}}

Displaying flash messages

Then, to display somewhere in your app, add this to your template:

{{#each flashMessages.queue as |flash|}}
  {{flash-message flash=flash}}
{{/each}}

It also accepts your own template:

{{#each flashMessages.queue as |flash|}}
  {{#flash-message flash=flash as |component flash|}}
    <h6>{{component.flashType}}</h6>
    <p>{{flash.message}}</p>
    {{#if component.showProgressBar}}
      <div class="alert-progress">
        <div class="alert-progressBar" style="{{component.progressDuration}}"></div>
      </div>
    {{/if}}
  {{/flash-message}}
{{/each}}

Styling with Foundation or Bootstrap

By default, flash messages will have Bootstrap style class names. If you want to use Foundation, simply specify the messageStyle on the component:

{{#each flashMessages.queue as |flash|}}
  {{flash-message flash=flash messageStyle='foundation'}}
{{/each}}

Sort messages by priority

To display messages sorted by priority, add this to your template:

{{#each flashMessages.arrangedQueue as |flash|}}
  {{flash-message flash=flash}}
{{/each}}

Rounded corners (Foundation)

To add radius or round type corners in Foundation:

{{#each flashMessages.arrangedQueue as |flash|}}
  {{flash-message flash=flash messageStyle='foundation' class='radius'}}
{{/each}}

{{#each flashMessages.arrangedQueue as |flash|}}
  {{flash-message flash=flash messageStyle='foundation' class='round'}}
{{/each}}

Acceptance / Integration tests

When you install the addon, it should automatically generate a helper located at tests/helpers/flash-message.js. You can do this manually as well:

$ ember generate ember-cli-flash

This also adds the helper to tests/test-helper.js. You won't actually need to import this into your tests, but it's good to know what the blueprint does. Basically, the helper overrides the _destroyLater method so that the flash messages behave intuitively in a testing environment.

An example integration test:

// tests/acceptance/foo-test.js

test('flash message is rendered', function(assert) {
  assert.expect(1);
  visit('/');

  andThen(() => {
    assert.ok(find('.alert.alert-success'));
  });
});

Styling

This addon is minimal and does not currently ship with a stylesheet. You can style flash messages by targetting the appropriate alert class (Foundation or Bootstrap) in your CSS.

Contributing

Please read the Contributing guidelines for information on how to contribute.

License

MIT

Installation

• git clone this repository
• npm install
• bower install

Running

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

Running Tests

• ember test
• ember test --server

Building

• ember build

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