Harmony

Get started

Harmony is a lightweight JavaScript library for building trivial widget or complex Single Page Application. It gives control back to model and view, by implementing publish-subscribe pattern, and provides an environment where model and view can live in harmony. Here are some of its features.

1. Lightweight client-side model with rich event features such as propagation, and cascading.
2. Unified subscription for both view and model
3. Subscription can be registered declaratively, programmatically, or mixed.
4. Reusable, functional, asynchronous event handler implemented by workflow and activity.
5. Bundled with lots of reusable, composable workflow types, activities, and subscriptions

Harmony is hosted on Github, it is available for use under the MIT software license.

Download

You can download Harmony from here. Harmony comes with two version, harmony.core.js (13KB) and harmony.js (20KB) which includes 10 plugins. The file size is after minified and gzipped.

Dependencies

1. jQuery 1.5+
2. jQuery BBQ (optional, required by bookmarkable plugins)
3. jsRender (optional, required by jsRender template adapter)
4. handlebars.js (optional, required by handlebars.js template adapter)
5. matrix.js (optional, required by external template plugins)

Installation

<script src="http://code.jquery.com/jquery-1.7.2.min.js"></script>
<script src="http://raw.github.com/fredyang/harmony/master/ref/jquery.ba-bbq.min.js"></script>
<script src="http://raw.github.com/fredyang/harmony/master/ref/jsrender.js"></script>
<script src="http://raw.github.com/fredyang/harmony/master/ref/matrix.min.js"></script>
<script src="http://raw.github.com/fredyang/harmony/master/download/harmony.js"></script>

Is Harmony a MVC framework?

No. Firstly, it does not use controller, secondly, it is not framework, but a library. You can call it Model-View-Subscription library.

MVC pattern works very well at server side. But client-side has some differences from server side, such as:

	Server side	Client side
Style	Predetermined machine to machine request/response	Not so predictable user/machine interaction
State	Stateless, state is created and destroyed for every request/response session	Stateful, state accumulates for every user interaction,and accumulates with time.
Event	No event	Events drive the application.
Controller	simple and well-controlled	complicated and hard to control

Because of the differences, Harmony use publisher-subscriber pattern. In this pattern, views and models take control of themselves by subscriptions. Below are the rules the library follows.

1. Views and models are all objects.
2. Objects control themselves.
3. No object control any other object.
4. An object can trigger events of himself.
5. An object cannot trigger events of others.
6. Objects can subscribe events and react.
7. Objects do not act without subscription.

Philosophy

When designing client application, we normally think like, "When this happens, I want to change this like this", such as "When view change, I want to change the model like this", or "When model change, I want to change view like this", or "Let's create a two-way binding between this view and this model, so that they can be synchronized".

Harmony use a different mindset, "When this happens, I want to change myself like this, other people will take care of themselves".

Can I use controller?

Yes, as long as it controls well. For whatever reason, such as performance, directly manipulating others is still required in some cases, you as a developer control what needs to be done.

Can I use with Harmony other MVC frameworks/libraries?

Yes. In Harmony, objects without subscriptions will do nothing, objects with subscriptions will only change themselves not others, so they are very harmless. Harmony is just a library about subscriptions, and it plays well with others.

The core of Harmony is based on the following modules.

1. Model
2. Unified Subscription
3. Workflow/activity
4. Template

Is the view module missing from the list? Yes, but it is deliberate. Most of the view features are taken care by jQuery, Harmony just add a couple of methods to jQuery object. In the following, I will give a overview on how each modules works. For details of each API, please refer to documentation.