prana
prana copied to clipboard
Prana Framework
Prana is a microframework for building modular and extensible node.js applications.
It provides an extensions system and metadata registry that help bringing organization, code reusability and extensibility to your project.
Extensions implement hooks for adding their bits of functionality and all kinds of application metadata, such as settings, database schema and other data elements that can be extended.
Beside hooks, Prana also collects data elements from JSON files, so you can easily distribute your extensions with everything they need in order to run.
Installation
$ npm install prana
Getting started
A very simple Prana application will look something like this:
var Prana = require('prana');
var app = new Prana();
app.init(function(extensions) {
// Do some application specific stuff.
});
For complete examples check the examples folder.
Extensions
Extensions allow you to build reusable components that can be easily shared through applications and application instances and also be extended by other extensions.
You can add extensions programmatically like this:
// The prototype of our programmatically created extension.
var myExtensionPrototype = {
// The myType() hook allow adding data elements for the 'myType' type and also
// altering the items created by other extensions.
myType: function(items, callback) {
var myTypeItems = {};
myTypeItems['some-item'] = {
title: 'Some item'
};
callback(null, myTypeItems);
},
// The collect() hook allow you altering items of all types when they get
// collected.
collect: function(type, items, callback) {
// Add a property to all types. You can use type to act only on items of a
// specific type.
for (var itemKey in items) {
items[itemKey].property = 'value';
}
callback();
}
};
// Add an extension programmatically.
app.extension('my-extension', {
title: 'My Extension',
description: 'This is just an example extension.',
prototype: myExtensionPrototype
});
But it's usually more useful having Prana scan a folder for extensions:
// Scan 'extensions' folder for extensions and add them.
app.loadExtensions(__dirname + '/extensions', function(error, extensions) {
// Do something with the just loaded extensions.
console.log('Loaded %d extensions.', Object.keys(extensions).length);
});
This will recursively scans a folder named 'extensions' looking for two kind of files: one named {extension-name}.extension.json
that contains extension information. And {extension-name}.js
that contains the extension prototype.
For example, you can have a folder called example
inside the extensions
folder of your application with example.extension.json
and example.js
files in it with the following content:
example.extension.json
{
"title": "Example Extension",
"description": "This is just an example extension."
}
example.js
var example = module.exports = {
// The collect() hook.
collect: function(type, items, callback) {
// Add a property to all types. You can use type to act only on items of a
// specific type.
for (var itemKey in items) {
items[itemKey].property = 'value';
}
callback();
}
};
Adding your own hooks
To add your hooks you can just use the invoke()
method and your hook will be called on all extensions:
var example = module.exports = {
collect: function(type, items, callback) {
// Invoke itemsDecoratorHook() on all extensions.
// This is where we "create" our hook.
this.invoke('itemsDecoratorHook', items, callback);
},
itemsDecoratorHook: function(items, callback) {
// Add a property to all types. You can use type to act only on items of a
// specific type.
for (var itemKey in items) {
items[itemKey].property = 'value';
}
callback();
}
};
Metadata registry
For getting metadata from the application registry you can use the collect()
and pick()
methods. Data elements will then be collected from hooks and JSON files.
// Collect all items of type 'myType'.
app.collect('myType', function(error, items) {
console.log(items);
});
// Pick a single item of type 'myType' with key 'some-item'.
app.pick('myType', 'some-item', function(error, item) {
console.log(item);
});
This is also how you add your own types. I.e. calling collect('myType', ...)
or pick('myType', ...)
will automatically create the myType()
hook for you.
Coding style
We try to conform to Felix's Node.js Style Guide for all of our JavaScript code. For coding documentation we use JSDoc style.