modularjs/README.md

Library for building events based apps

# ModularJS

<summary><i>ModularJS is an events based and modular framework for building node's apps or browser's apps. It was inspired by scaleApp and flightjs.</i></summary>

## Install
Add the script in your html, **no dependencies required**.
```html
<script src="dist/modular.min.js"></script>
```
or with npm
`npm install modularjs`

## Usage

### **Container([common])**
Create a new container
```js
//if using browser version
var App = new Container();
//or
var App = new Container({
	jQuery: $,
  commonProperty: "i am common",
  ...
});

//if using node version
var modularJS = require('modularjs');
var App = new modularJS.Container();
//or
var App = new modularJS.Container({
  jQuery: $,
  commonProperty: "i am common",
  ...
});
```

<dl>
<dt><strong>common</strong></dt>
<dd><i>[Object] optional - Default <code>{}</code></i>. Shared object between all components, usefull for sharing library accross your application. <br>As you can see in the next example, the object is not sync between components. So if a component modify a property, the change won't affect other components.
For sync property view <code>App.set(name, value, [overwrite])</code>.
</dd>
</dl>

### **App.addComponent(name, constructor)**
Add a component to the container
```js
App.addComponent("people", function(city){
	this.name = "Henry";
    this.city = city;
    console.log(this.commonProperty); //Output: "i am common"
    this.commonProperty = "i am a modified common";
    console.log(this.commonProperty); //Output: "i am a modified common"
});
//same as
var peopleComponent = function(city){
	this.name = "Henry";
    this.city = city;
    console.log(this.commonProperty); //Output: "i am common"
}
App.addComponent("people", peopleComponent);
```
<dl>
<dt><strong>name</strong></dt>
<dd><i>[String] required</i>. Name of the component, must be unique.</dd>
<dt><strong>Constructor</strong></dt>
<dd><i>[Function] required</i>. Constructor of the component.</dd>
</dl>

### **App.addComponentExtend(name, extend, constructor)** ###
Add a component that extend a class to the container

```js
var Person = function(){
  	this.showName = function(){
  		console.log(this.name);
  	}
};
App.addComponentExtend("people", Person, function(city){
	this.name = "Henry";
    this.city = city;
    this.showName(); //Output: "Henry"
});
//same as
App.addComponentExtend("people", new Person(), function(city){
	this.name = "Henry";
    this.city = city;
    this.showName(); //Output: "Henry"
});
//or you can pass an object too
App.addComponentExtend("people", {
	showName : function(){
  		console.log(this.name);
  	}
}, function(city){
	this.name = "Henry";
    this.city = city;
    this.showName(); //Output: "Henry"
});
```
<dl>
<dt><strong>name</strong></dt>
<dd><i>[String] required</i>. Name of the component, it should be unique.</dd>
<dt><strong>extend</strong></dt>
<dd><i>[Function / Object] required</i>. Class or object inherited by the component.</dd>
<dt><strong>Constructor</strong></dt>
<dd><i>[Function] required</i>. Constructor of the component.</dd>
</dl>

### **App.set(name, value, [overwrite])** ###
Set a shared synchronized variable between all components.<br>
See `Component.containerGet()` for more information.

```js
App.set('AppVersion', '2.1.0');
//or if AppVersion already exist
App.set('AppVersion', '2.1.0', true);
```

<dl>
<dt><strong>name</strong></dt>
<dd><i>[String] required</i>. Name of the property.</dd>
<dt><strong>value</strong></dt>
<dd><i>[Mixed] required</i>. Value of the property.</dd>
<dt><strong>overwrite</strong></dt>
<dd><i>[Boolean] optional - Default <code>false</code></i>. If true set the value event if the property has already been set. If false set the value if the property has <strong>not</strong> already been set</dd>
</dl>

### **App.addMixin(name, mixin)** ###
Add a mixin that can be required in any components.<br>
`this` use the context from the component where the mixin is called.

```js
App.addMixin('setName', function(name){
	this.name = name;
});
//same as
var setNameMixin = function(name){
	this.name = name;
};
App.addMixin('setName', setNameMixin);
```
<dl>
<dt><strong>name</strong></dt>
<dd><i>[String] required</i>. Name of the mixin, must be unique.</dd>
<dt><strong>mixin</strong></dt>
<dd><i>[Function] required</i>. The mxin itself.</dd>
</dl>

### **App.run()** ###
Create instance of all components. Can be call with several constructors.
```js
App.run();
App.run(name);
App.run(name, args);
App.run(name, callback);
App.run(name, args, callback);
App.run([name, ...]);
App.run([name, ...], args);
App.run([name, ...], callback);
App.run([name, ...], args, callback);
```
You can call it multiple times
```js
App.run('componentTest1');
App.run('componentTest2');
App.run();
/*
* Will instantiate in order
* - componentTest1
* - componentTest2
* - all other components that are not yet instanciated
*/
```
A component can only be run once so if you do :
```js
App.run('componentTest1');
App.run('componentTest1');
//componentTest1 will gonna be called only the first time
```

<dl>
<dt><strong>name</strong></dt>
<dd><i>[String / Array] optional - Default <code>"*"</code></i>. Name of the component(s) to instanciate. If equal to <code>"*"</code> instanciate all components in the order they have been added.</dd>
<dt><strong>args</strong></dt>
<dd><i>[Array] - Default <code>[]</code></i>. Arguments passed to the component's constructor.</dd>
<dt><strong>callback</strong></dt>
<dd><i>[Function] - Default <code>null</code></i>. Function called after all passed components are instanciated. No arguments supported.</dd>
</dl>

## Components
In this section we gonna see what you can do inside your components.
So first let's take an example.
```js
App.addComponent("people", function(city){
	this.name = "Henry";
    this.city = city;
});
```

We need to run our component so let's call
```js
App.run("people", ['Paris'], function(){
	console.log('People has been called, his city is Paris');
});
```

Components extends node's event emitter so inside your component you can call
```js
this.on('myEvent', function(){
	console.log('my event triggered');
});

this.emit('myEvent');
```

ModularJS add two function in the event emitter
```js

this.before('myEvent', function(){
	console.log('before my event triggered');
});

this.after('myEvent', function(){
	console.log('after my event triggered');
});
```

Let's require some mixins.

### **Component.mixin(name)** ###
Include a mixin inside your component

```js
var setName = this.mixin('setName'); //Return false if no mixin with the passed name found
setName('Pierre');
console.log(this.name); // Output: "Pierre"
```

<dl>
<dt><strong>name</strong></dt>
<dd><i>[String] required</i>. Name of the mixin.</dd>
</dl>

### **Shared properties**
Let's see more about shared properties across components.
For setting them see `Container.set` method above.

Inside your component you can manipulate those properties with three methods:

```js
this.containerGet(name); //Return the property value
this.containerSet(name, value, [overwrite]) //Set the property value
this.containerAdd(object, [overwrite]); //Merge the passed object with the shared object
this.containerDelete(name); //Delete the property
```

If a property is a function you can call her with
```js
this.containerExecute(name); //Execute the function
//you can pass arguments to the called function like this
this.containerExecute(name, arg1, arg2, arg3);
```

Like mixins, `this` use the context from the component where the function is called.

## Contributions:
Feel free to send pull requests.

### For developement
```
git clone https://github.com/PIC-27/modularJS.git MyApp
cd MyApp
npm install
npm run gulp
```