rob-murray / ui-message-queue

User Interface Message Queue Javascript implementation

ui-message-queue AKA User Message Queue Javascript implementation

Description

ui-message-queue is a Javascript implementation of a message queue allowing you to push messages (simple Strings) to the queue and display in a DOM element via a First In First Out (FIFO) method. This means that you can load up messages and they each have a defined display time after which will be overwritten with the next message or cleared.

The goal is to be as simple as possible to include and use, it's meant for displaying messages to website users rather than queuing backend type tasks.

Check out a demo here.

Features:

• No jQuery! Whilst fantastic as it is, can this is intended as a standalone library and not rely on other frameworks - so we're a jQuery free zone.
• Add messages to queue; displayed in FIFO order.
• Select the DOM element to update, falling back to Javascript Alert if not found.

Getting started

1. Get hold of the library:

Bower

Install from bower.io

$ bower install ui-message-queue --save

Copy javascript file

Copy Javascript source from lib/ui-message-queue.min.js or lib/ui-message-queue.js to your project.

2. Import source file.

<script type="text/javascript" src="ui-message-queue.min.js"></script>

Or however you require libraries.

3. Configuration

Takes options in the form of an object literal:

options = {
  outputElementId: "output-id",
  delay: 2000,
  emptyDisplayString: "A String"
};

These are as follows:

• outputElementId - [OPTIONAL] - The ID of the element in the DOM to add messages to. If this is not found then ui-message-queue falls back to using the alert popup box
• delay - [OPTIONAL] - Time in milisecs to display each message for. Throws "Invalid argument" Error if not numeric. Default value is 1000 or 1 second.
• emptyDisplayString - [OPTIONAL] - This is message displayed when no messages are in the queue. Default val is "..."

4. Create instance of object passing options.

var messageQueue = new UiMessageQueue(options);

5. Add messages to the queue.

messageQueue.push("Here is a message");
messageQueue.push("Here is another one");
messageQueue.push("Finally, one more message");

These will be displayed in a first in-first out manner with each message displayed for the set period of time.

See the demo for a cool, super useful example.

Contributions

Please use the GitHub pull-request mechanism to submit contributions.

Edit the coffeescript source and then compile to js - Do not edit ui-message-queue.js

Contents

This repository contains the following sections:

1. src - this contains the source Coffeescript.
2. lib/ui-message-queue{.min}.js - the source is then compiled into Javascript and minified (copy this to use!).
3. test/*_spec.coffee - the tests implemented in Mocha and Chai.
4. example/index.html - some real life html with proper Javascript to test this project.

Testing

Run all tests.

$ grunt test

Code style

Run CoffeeLint over the source:

$ grunt coffeelint

Build

To produce a release build, run the build script; this compiles to JS and merges into one file to produce src/ui-message-queue.js and lib/ui-message-queue.min.js.

$ grunt build

License

This project is available for use under the MIT software license. See LICENSE

ui-message-queue's Issues

Unable to test DOM interaction

The spec for DomDisplay class is disabled at the moment as I cannot test anything that requires a DOM - this just needs investigation into how to do this with jasmine-node && any other libs.

The tests for 'display messages from queue' are disabled

The tests for display messages from queue are currently disabled due to being unable to get jasmine.Clock.tick to work correctly so that we can test processing messages in the queue.

These tests are important in order to test the _processMessageQueue method and so major chunk of the code.

Additional option argument to leave last message text displayed

Hi,

Logged issue with last message text remaining displayed. Perhaps this could be introduced as an enhancement via main options, whereby last message pushed to queue remains displayed (or not, according to option set).

Message text not clearing from dom element

Hi,

I have an options delay of 0, and an emptyDisplayString of "".

On occasion I push several messages to queue in quick succession. The last message pushed remains displayed within the dom element i.e. not "expiring".

Thanks.

Additional option argument for lifetime of message

Hi,

Great work. Possible to add additional option argument for lifetime of message show upon push to queue?

Thanks.

Incorrect options parameter in spec

The describe 'default options' block uses the incorrect options param name of message_box_div_id - this is irrelevant to the tests but for consistency should be updated.

This block can disappear if #6 is fixed/improved.

Create gh-pages branch for demo

It's a nice way to demo your great work without users needing to clone the repo.

I forked and created the pages branch, but unfortunately, I cannot send a pull request for a new branch.
http://alampros.github.com/ui-message-queue/

Additional argument for element id upon queue push

Hi,

What's your thoughts on enabling additional argument for specifying DOM element ID upon message push, as I have a need to funnel messages to different display elements.

Thanks.

Demo doesn't work

http://rob-murray.github.com/ui-message-queue fails in Chrome.

Refused to execute script from 'https://raw.github.com/rob-murray/ui-message-queue/master/ui-message-queue.js' because its MIME type ('text/plain') is not executable, and strict MIME type checking is enabled. rob-murray.github.io/:1
Uncaught ReferenceError: UiMessageQueue is not defined 

On init UiMessageQueue should write the empty message string to the elem contents

When creating a new instance should we write that to the DOM immediately? Possibly an option to enable/disable this?

Given a valid DOM element id as an option
When a new instance of UiMessageQueue is created
Then the 'emptyQueueMessage' should be written to the DOM element

Given an invalid DOM element id as an option
When a new instance of UiMessageQueue is created
Then no Alert message should be displayed

Incorrect behaviour regarding options passed

The behaviour at present is to throw Error when no options passed, however all options are optional so you should be able to init a new UiMessageQueue without any arguments.

component.json for bower/component