conversation

Conversation

Highlights

• Added JS Docs
• Added Build Tools (configuration required)
• Added "Hallways" - Communcation channels between client Rooms and server Rooms

Installation

For client-side usage, simply download the js file out of the repo root. For server-side usage with NodeJS, install 'conversation' using 'npm'.

What is Conversation?

Conversation is an architectural platform that allows you to develop loosely coupled, dynamic applications by giving you a new way to call functions, access objects, modify datamembers, and much more. Traditionally, explicit calls coupled segments of your software together. Components would access and call on one another directly within their scope.

Conversation will allow your application will make calls in an entirely new and dynamic fashion. Rather than coupling your components together into an unmaintainable nightmare, you can abstract away components from one another, allowing you to write more code and worry less about down the road.

The Traditional Way

Lets look at a quick example of a typical status-quo application:

	var speak = function(params){
		console.log(params.text); //function coupled to bare-metal
	};
	var shout = function(params){
		console.error(params.text); //function coupled to bare-metal
	};
	var sayGoodbye = function(params){
		console.log('Goodbye!'); //function coupled to bare-metal
	};
	var error = function(str){
		shout('Error!->'+str); //function coupled to function
		sayGoodbye(); //function coupled to function
	};
	var okay = function(str){
		speak('Everything is okay->!'+str); //function coupled to function
		sayGoodbye(); //function coupled to function
	};

Then you would use these functions when certain things happen within your software:

    function thereIsAProblem(problem){
        error(problem); //nested coupling (VERY bad)
    }
    function everythingIsOkay(thing){
        okay(thing); //nested coupling (VERY bad)
    }

While a gorilla could tell that this example is an over-complicated way of using the console object, this also serves as a good example of the status-quo spaghetti code that most web applications will evolve into if left to their own demise without proper planning.

The problem with this methodology (explicit function calls) is that you end up with hard references between different components in your application. Sure, it is familiar and anything familiar seems simple, but you cannot easily swap out the error function with a function of a different name that performs a different task; nor, can you inject and execute a second function on the fly(like reporting the error via AJAX) when thereIsAProblem is executed. Worse yet, such implementation tends to lead to chains of dependency, and on large projects all it takes is a single developer changing the way a single function behaves to damage your application in a way that not only brings it to its knees, but is incredibly difficult to trace. In order to write better code, you have to use a better methodology.

The 'Conversation' Way - 100% Pure, Well-designed JS Goodness

Now, lets look at how we could accomplish this same static task with a Conversation:

    //First, we create a Conversation Room
    var convo = require('Conversation'); //Load the package
    var ConvoRoom = convo.newRoom(); //this creates a new 'Room' for a conversation



	//Now, we create the functions the same way as before!
    var speak = function(params){
        console.log(params.text); //function coupled to bare-metal
        return 'said'; //said will get loaded into the return object
    };
    var shout = function(params){
        console.error(params.text);
        return 'shouted';
    };
    var sayGoodbye = function(params){
        console.log('Goodbye!');
        return 'exited';
    };




	//Finally, we tell the functions to listen for a word
    ConvoRoom.listen('error',shout,'shout');  //this tells 'shout' to listen for the word 'error' and dump its return into 'shout'
    ConvoRoom.listen('error',goodbye,'bye');  //this tells 'goodbye' to listen for the word 'error' and dump its return into 'bye'

	/*The third parameter tells Conversation to load any value that shout returns
	into a JSO which is returned to the speaker after all calls have been invoked*/

	ConvoRoom.listen('okay',speak,'speak'); //this tells 'speak' to listen for the word 'okay' and dump its return into 'speak'
    ConvoRoom.listen('okay',goodbye,'bye'); //this tells 'goodbye' to listen for the word 'okay' and dump its return into 'bye'


	//Here, these two functions speak.
    var error = function(str){
        var result = ConvoRoom.speak('error',{text: "Error! ->"+str}); //shout and goodbye just heard this and dumped their returns into result
		console.log(result.shout,result,bye); //you can access returned types this way
	};
    var okay = function(str){
        var result = ConvoRoom.speak('okay',{text: "Everything is okay -> "+str}) //speak and goodbye just heard this and dumped their returns into result
		console.log(result.speak,result,bye); //you can access returned types this way
	};

Aha! Now none of our functions are bound to anything but the Conversation that they participate in. They don't care who/what handles their request, as long as they are served satisfaction.

With Conversation, components no longer reference each other at all. In fact, they don't need to know that anything but themselves exist! Components listen to Conversations and react to Words spoken by other Components. Each component acts as a Listener, and is bound to one or more Words. If a Component needs to access external functionality or pass information along, it simply Speaks a word within its Conversation. Any other components that are listening for that word will then react to it and perform a job. If any of the Listeners return any output, it is collected and passed back en-masse to the Speaker in the form of an Object.

Conversation is ready for include with NodeJS, and extends jQuery for front end usage:

    var conv = require('Conversation'); //NodeJS
    var room = conv.newRoom();


    var room = $.Conversation.newRoom(); //jQuery

Learn More - The "Next" Next big thing...

The uses for Conversation are not only limited to function calls, but can be used in any situation where a function, data member, object, or even an entire architectural segment needs to be accessed or manipulated in some way. If you cannot yet decide whether or not the Conversation way is right for you, head on over to our Wiki and take a look at some other ways to take advantage of our methodology.

Conversation is, and always will be, 100% compatible with NodeJS as well as front-end frameworks.

    Copyright (c) 2012 The Jupiter Project, Andrew E. Rhyne

    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal in
    the Software without restriction, including without limitation the rights to use,
    copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
    Software, and to permit persons to whom the Software is furnished to do so, subject
    to the following conditions:

    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
    INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
    PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
    FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
    OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
    IN THE SOFTWARE.

    For more information regarding this software, feel free to drop me a line:
    [e-mail]