HubSpot Messaging Library

• Show transactional messages in your app.
• Wrap AJAX requests with progress, success and error messages.
• Add action links to your messages.
• 4kb minified and compressed.
• Works in everything modern, and IE7 and above.

Demo

Requires

• jQuery
• Plays well with, but doesn't require, Bootstrap

Including

JS

/build/js/messenger.min.js
/build/js/messenger-theme-future.js

CSS

/build/css/messenger.css
/build/css/messenger-theme-future.css

Also available as a Rails gem and on cdnjs.

Really Quick Usage

# Replace:
$.ajax
    url: "/some-url"
    success: ->

# With:
Messenger().run
    errorMessage: "This did not go well."
,
    url: "/some-url"
    success: ->

Usage Click Code to Edit

Messenger().post "Your request has succeded!"

Messenger().post
    message: 'There was an explosion while processing your request.'
    type: 'error'
    showCloseButton: true

msg = Messenger().post "My Message"
msg.update "I changed my mind, this is my message"
msg.hide()

# Want to put actions at the end of your messages?
msg = Messenger().post
    message: 'Launching thermonuclear war...'
    type: 'info'
    actions:
        cancel:
            label: 'cancel launch'
            action: ->
                msg.update
                    message: 'Thermonuclear war averted'
                    type: 'success'
                    actions: false

# This guy will 500 a few times, then succeed
i = 0
Messenger().run
  errorMessage: 'Error destroying alien planet'
  successMessage: 'Alien planet destroyed!'

  action: (opts) ->
    if (++i < 3)
      opts.error({status: 500, readyState: 0, responseText: 0})
    else
      opts.success()


# Have an error? How about auto retrys with a Gmail-style countdown
# (hidden in the future theme)?:
msg = Messenger().post
    message: "I'm sorry Hal, I just can't do that."
    actions:
        retry:
            label: 'retry now'
            phrase: 'Retrying TIME'
            auto: true
            delay: 10
            action: ->
                # Do some retrying...

        cancel:
            action: ->
                do msg.cancel

# You can bind to action events as well:
msg.on 'action:retry', ->
    alert('Hey, you retried!')

# Need more control? You can bind events backbone-style based
# on the type of message.
msg.update
    events:
        'success click': ->
            # Will fire when the user clicks the message
            # in a success state.

        'error click a.awesome-class': ->
            # Rock on

# Need your message to hide after a while, or when the Backbone
# router changes the page?
Messenger().post
    message: "Weeeeee"

    hideAfter: 10
    hideOnNavigate: true

# You can use the id property to ensure that only one
# instance of a message will appear on the page at a time
# (the older message will be hidden).
Messenger().post
  message: "Only one at a time!"
  id: "Only-one-message"

# When you add the singleton attribute, it ensures that no
# other messages with that id will ever be shown again
# (the newer message will be hidden).
Messenger().post
  message: "It's just me!"
  id: '4'
  singleton: true

Messenger().post
  message: "You'll never see me"
  id: '4'
  singleton: true

# Rather than hiding and showing multiple messages
# you can also maintain a single message between
# requests.
msg = Messenger().run()
Messenger().run({messageInstance: msg})

# Don't want your message hidden on a long page? (Not necessary
# if you're using the default fixed positioning)
msg = Messenger().post
    message: "You'll see me!"

    scrollTo: true
    # Requires jQuery scrollTo plugin

msg.scrollTo() # also works

# Lazy/smart? How about messenger does it all for you?  All the
# retry magic comes with.
Messenger().run
    successMessage: 'Data saved.'
    errorMessage: 'Error saving data'
    progressMessage: 'Saving data' # Don't include messages you
                                   # don't want to appear.

    # Any standard message opts can go here
,
    # All the standard jQuery ajax options here

    url: '/data'

# Need to override the messages based on the response?
Messenger().run
    errorMessage: 'Oops'
,
    url: '/data'
    error: (xhr) ->
        # Whatever you return from your handlers will replace
        # the default messages

        if xhr?.status is 404
            return "Data not found"

        # Return true or undefined for your predefined message
        # Return false to not show any message

        return true

# Sometimes you only want to show the success message when a
# retry succeeds, not if a retry wasen't required:
Messenger().run
    successMessage: 'Successfully saved.'
    errorMessage: 'Error saving'

    showSuccessWithoutError: false
,
    url: '/data'

# You don't have to use $.ajax as your action, messenger works
# great for any async process:
Messenger().run
    successMessage: 'Bomb defused successfully'

    action: defuseBomb
    # You can put options for defuseBomb here
    # It will be passed success and error callbacks

# Need to hide all messages?
Messenger().hideAll()

# If your action responds with a promise-like thing, its
# methods will be copied onto the message:

Messenger().run({}, {url: 'a'}).fail(-> alert "Uh oh")

# Do you use Backbone? Hook all backbone calls:
Messenger().hookBackboneAjax()

# By default, there will be no error message (just background
# retries), return an error message from your backbone error handler,
# or add an errorMessage to the messenger opts to set one.
# You can override these options by passing them into
# hookBackboneAjax, or adding a {'messenger': } hash to your
# fetch call.

# You don't have to use the global messenger
$('div#message-container').messenger().post "My message"

# By default, the global messenger will create an ActionMessenger
# instance fixed to the bottom-right corner of the screen.

# You can pass an instance of messenger into globalMessenger
# to override the default position.
myAwesomeMessenger = $('.mess').messenger()
Messenger({instance: myAwesomeMessenger});

Messenger() # <-- Will return your messenger

Messenger({'parentLocations': ['.page', 'body']});
# Will try to insert the messenger into the el matching
# .page before inserting it into the page.

# This can be important if you're not using fixed positioning.

# All the options for globalMessenger and their defaults:

{
  'parentLocations': ['body'],
  'maxMessages': 9,
  'extraClasses': 'messenger-fixed messenger-on-right messenger-on-bottom messenger-theme-future',
  'instance': undefined,
  'messageDefaults': {
    # Default message options
  }
}

# You can also set default options on the Messenger.options object.
Messenger.options = {'extraClasses': 'messenger-fixed messenger-on-left'}

Contributing

We welcome contributors!

The build process requires nodejs and grunt-cli. You can build the output files by running grunt. The automated tests can be run by opening SpecRunner.html in a browser.

There is plenty to be done, pick an issue and start hacking!