Fork me on GitHub

envelope.js

Envelope.js is a simple, event driven jQuery plugin for in app messaging designed to work with or without popular UI frameworks.

Decouple your user feedback messages from the functions that generate them.

Have you ever written code that looks like this?

If so, you quickly find out that you are writing a lot of display code in your callbacks, that its hard to reuse this code, and its hard to maintain this code.

$.ajax({
    url : ...,

    success : function(){
        $msg = $("<p>Success saving.</p>")
               .hide();

        $('#messages').append(
            $msg;
        );

        $msg.fadeIn("slow");
    },

    error : function(){
        ...
        }
})

Using envelope, your callbacks become much more elegant

Envlope allows you create messages that listen for events and display a message when that event is triggered.

$.ajax({

    url : ...,

    success : function(){
        $.trigger('save.success')
    },

    error : function(){
        $.trigger('save.error');
    }
});

Try it!

Use the form below to setup an event and trigger it by clicking the "Generate Event" button

Generate Event

Get it!

Getting Started

Getting started is easy:

  1. Download the code using the links in the Get it! section or visit the GitHub page.
  2. If you want to use the default styles add the envelope.css stylesheet to your page, if you are using jQueryUI or Twitter's Bootstrap you don't have to do anything envelope will use the styles included in those frameworks.
  3. Attach envelope to a DOM element and pass it some events to listen to.
  4. Trigger events to display messages.

Setup

To setup envelope, just attach it to a jQuery wrapped element and pass it some arguments.

The first, and optional, argument is the plugin options. These specify the UI framework to use and the default timeout before auto-close elements disapear.

The second argument to pass in is an array of event options. The event options define the behavior of the events to listen to. 

$("#messages").envelope(
    { //plugin options
        uiFramework: 'bootstrap',
        autoCloseTimeout: 5000
    },
    [ //array of events, with options
        {
            name: 'user.save',
            message: "User saved.",
            callback : function(){},
            autoClose: true,
            addCloseButton: true,
            type: 'success'
        }
    ]
);

Arguments & Options

Plugin Options

The first, and optionl, argument that is passed into the plugin are the options for the plugin itself.

uiFramework
bootstrap | jqueryui | none
autoCloseTimeout
ms before message automatically closes

Event Options

The second option is an array or events that envelope should listen for. Each even has its own set of options.

name
name of event to listen for
message
text to display to user
callback
callback to execute when the event is triggered
autoClose
boolean value to specify weather message auto closes
addCloseButton
boolean value to specify to add close button or not
type
success | error | info

Methods

add(event_options)

You can add events to the plugin after initialization by using the add method.

$("#messages").envelope('add',
    {
        name : 'test.success',
        message: 'Success saving test.',
        type: 'success',
        addCloseButton : true,
        autoClose : true
    }
);

remove(event_name)

You can remove events to the plugin after initialization by using the remove method.

$("#messages").envelope('remove','test.success');

Appending Text To Messages

To append text to a message when the event is triggered just pass the additional text as the second parameter of the trigger()method.

$("selector").trigger("save.success","Additional text");