README.md

Hermes, the notifier

Hermes is a notification message manager.
It deals with your messages in your page's interface.
It manages multiple messages at a time.
It's cleaner, ligher.
It allows you to use react components within the message, making it a powerfull tool.

It can be used to replace other messagers. Has a lighter, malleable design and animations.
You can even manage messages by id or simulate a loading controller.

Take a look.

See how to do this in the examples below.
Test it live, in the demo tool.

Installing

npm install --save reactive-hermes

Using it

You need to import and add the HermesComponent to your interface.
You should do that once, let's say, in your root page for example.

// used only once
import { Hermes, HermesComponent } from 'reactive-hermes'

[...]

<HermesComponent />

Now, you can access the global Hermes object, or import it in your modules and then use its API, described below.

// used anywhere
import { Hermes } from 'reactive-hermes'
// or
import Hermes from 'reactive-hermes'

[...]

Hermes.message('The message')
// or
window.Hermes.message('The message') // does not require to be imported

API

Let's see some of the cool things you can do with it!

Props

You can send some props to enforce a default behavior:

• defaultDuration: An integer representing the duration of the message in seconds. By default, it will not close itself.
• updateTitleCounter: Boolean. If present, will update the page's title adding the number of open notifications. Like (2) Page Title.
• playAudio: Boolean/AudioObject. You can simply use the playAudio attribute in the tag to use a default audio or pass a value to it with an Audio Object (to customize the audio).
• animate: Animates all the message icons, except for messages that overwrite it.

<HermesComponent
  defaultDuration={999}
  updateTitleCounter
  playAudio={new Audio(...)}
  animate />

Methods

These are methods you can access at Hermes:

• Hermes.message(String)
  This is an easy way to show a message.

• Hermes.message(Object)
  This is the advanced way to show messages.
  It accepts an object with:

  • type: It may be default, warn/warning, error/fail, info or success
  • body: This is the message itself. It may be a ReactComponent or a String
  • [id]: An optional id for the message
  • [playAudio]: Overwrites the global playAudio attribute for this particular message. May be true/false or an AudioObject
  • [duration]: The duration in seconds for the message to close itself. This will overwrite the defaultDuration global attribute.
  • [locked]: Hides the "x" button to close the message. Requires an id. May only be closed programatically
  • [animate]: Enabled the animation for the message icon

• Hermes.updateMessage(Object)
  Allows you to update an existing message. If the message is not opened, it will be shown.
  The object must have an id for the message to be updated.

• Hermes.closeMessage(String/Number)
  Closes an open message with the given id

Aliases

Aliases work just like the methods, but using different default values.

• Hermes.info(message[, options])
  Equivalent to use Hermes.message passing type 'info'.
• Hermes.warn(message[, options]) OR Hermes.warning(message[, options])
  Equivalent to use Hermes.message passing type 'warn'.
• Hermes.error(message[, options]) OR Hermes.fail(message[, options])
  Equivalent to use Hermes.message passing type 'error'.
• Hermes.success(message[, options])
  Equivalent to use Hermes.message passing type 'success'.

Events

You can use this events in the one tag for the HermesComponent, so, the listener will be called everytime any message triggers the given event. Or you can pass the eventListener on each individual message to listen for only its event.

• onMessageOpen: Will be trigger after ending the message animation for showing the message.
• onMessageClose: Will be trigger after ending the message animation for closing the message.
• onMessageUpdate: Will be trigger after updating a message.
• onInfo: Triggered when a message of type info is shown.
• onWarn: Triggered when a message of type warn is shown.
• onError: Triggered when a message of type error is shown.
• onSuccess: Triggered when a message of type success is shown.

Compatibility

Are you using methods like showWarning and showSuccess?
No problem, you can just import them from Hermes too!

import { showerror, showSuccess } from 'reactive-hermes'

Examples

See some ways you can show messages

Showing a success message:

let message = 'You are the chosen one.';
Hermes.success(message);
Hermes.success(message, { /* other options */ });
Hermes.message({
  type: 'success',
  body: message
})

Result:

Showing a warning:

let message = 'You have been warned!';
Hermes.warn(message);
// show the warning, animating its icon
Hermes.warn(message, { animate: true });
Hermes.message({
  type: 'warn',
  body: message
})

Result:

Showing an error:

let message = 'Something is out of order!';
Hermes.fail(message);
Hermes.error(message);
Hermes.error(message, { /* options */ });
Hermes.message({
  type: 'error',
  body: message
})

Result:

Showing an info:

let message = 'Info messages, wohoo!!';
Hermes.info(message);
// show info and play audio
Hermes.info(message, { playAudio: true });
Hermes.message({
  type: 'info',
  body: message
})

Result:

Showing a locked message:

let message = 'Yet another useless message';
Hermes.message({
  body: message,
  id: 'myMessageId',
  locked: true
})

Result:

Updating a message programatically:

let message = 'Saving...';
Hermes.message({
  body: message,
  id: 'savingMsg',
  locked: true,
  animate: true
})

Then, some time later...

Hermes.updateMessage({
  body: 'Saved',
  id: 'savingMsg',
  locked: true,
  animate: false,
  duration: 3 // 3 seconds
})

Result:

Showing message containing a ReactComponent:

Hermes.message(<div>Content here :)</div>)
// or
Hermes.message({
  // ...
  body: <SomeComponent prop1={val} />
  // ...
})

Result:

Customizing styles

You can add changes to the following CSS selectors:

• #hermes-container: The container in which all the messages will be appended to
• .hermes-notif: Each of the notifications
• .hermes-remove-message: The x button in unlocked messages, to close them
• .hermes-error/.hermes-warn/.hermes-info/.hermes-default: Same as .hermes-notif, but selected by message type

Contributing

Feel free to contribute to this project by sending Pull Requests, reporting problems or even sending suggestions.
Just remember to follow the community terms/rules/good practices :)

How to contribute

Once you've cloned the project...

Install:
npm install

Start the server (this will also enable the live/hot reload for the component):
npm start

Make chages:
Work in the src/ files, or in the demos/src/ files, or in css/ files.

Build:   npm run build

Then push it and open a PR :)