I have set up a few projects with TerrificJS and I have to say it’s great! With TerrificJS I don’t have to wonder about how to organize my javascript source code. The structure is taken care of. The timing is taken care of. There’s no danger of one module’s code getting in the way of another. So what’s a module? TerrificJS handles modules much like OOCSS. OOCSS is a CSS framework which gives common components or modules (I’ll stick with module) a blueprint structure.
Here’s a minimum module structure (see OOCSS Modules for more details).
<div class="mod MyModulenName">
<div class="inner">
<div class="bd">
My Module contents goes here.
</div>
</div>
</div>
What if you would like to use TerrificJS in your existing website which does not use the OOCSS structure for it’s modules? Doesn’t matter – you can, with RegisterModule. More of that later in this post.
Adding TerrificJS to your website
You will need to download jQuery and TerrificJS:
Include both files, first jQuery and the TerrificJS.
<script src="http://code.jquery.com/jquery-1.6.4.min.js" ></script>
<script src="/yourpath/terrific-1.0.0.min.js" ></script>
The Bootstrap
jQuery and TerrifficJS are included. Next the TerrificJS Bootstrap needs to be added.
<script src="http://code.jquery.com/jquery-1.6.4.min.js" ></script>
<script src="/yourpath/terrific-1.0.0.min.js" ></script>
<script >
// TerrificJS bootstrap
(function($) {
$(document).ready(function() {
var $page = $('body');
var application = new Tc.Application($page);
application.registerModules();
application.start();
});
})(Tc.$);
</script>
The TerrificJS Bootstrap is added after the jQuery and TerrificJS libraries. A lot is happening here.
jQuery noConflict
First of all TerrificJS makes use of jQuery noConflict (also have a look at the TerrificJS uncompressed source code).
Tc.$ = jQuery.noConflict(false); // Part of TerrificJS source
This explains the self-executing function which begins on line 4 and ends on line 11. Tc.$, which is a reference to jQuery, is passed on to $. Inside the self-executing function $ can be used to access jQuery. This saves on code and time.
If you need jQuery to be assigned to the dollar variable $ then add the following line after the TerrificJS bootstrap code:
$ = Tc.$ // This goes after the TerrificJS bootstrap
Application context
Line 6 sets the context. If nothing else, the html body containing the visible part of your website is the context.
var $page = $('body');
You could apply TerrificJS to a much smaller area on your website if you don’t want the whole DOM to be scanned by TerrificJS.
var $page = $('#someOtherContainerActingAsContext');
Getting the party started
Lines 7 and 8 initialize the application/website. The context is passed to Tc.Application and all modules are registered. This is where OOCSS comes in. TerrificJS looks for all html elements with the css class mod. It then looks for a second css class with the prefix modMyModuleName. You can see all the naming conventions used by TerrificJS on http://www.terrifically.org/learn/basics/conventions. Does this mean you need to add a mod and modMyModuleName to all your already existing modules on your website? No. Carry on reading.
Using TerrificJS without OOCSS
You’re not starting from scratch and would like to add TerrificJS to your existing website. No problem. Let’s say you your main navigation html looks like this.
To treat the div with the id MainNav as a module the following line needs to be added to the TerrificJS Bootstrap.
application.registerModule($('#MainNav'), 'MainNav');
The first parameter is the jQuery object of the module and also the jQuery context used. The second parameter is the name of javascript class used by TerrificJS. For more information on the parameters see registermodule.
Module Javascript Class
The predefined methods used in the code below are explained on http://www.terrifically.org/learn/module. Putting it all together:
(function($) {
Tc.Module.MainNav = Tc.Module.extend({
init: function($ctx, sandbox, modId) {
// call base constructor
this._super($ctx, sandbox, modId);
},
dependencies: function() {
//this.require('File.js', 'util', 'beforeBinding');
},
beforeBinding: function(callback) {
var $ctx = this.$ctx;
// Put code that only depends on the existance of this
// dom readyness of this module
callback();
},
onBinding: function() {
var $ctx = this.$ctx;
// Put all your code in here that also depends on the
// dom readyness of other modules. For example if
// this module communications with other modules via
// connectors.
// You're on the safe side if you put all your code
// here.
// Example: Change the background color of this
// instance of div#MainNav
$ctx.css('background-color', 'red');
},
afterBinding: function() {
var $ctx = this.$ctx;
}
});
})(Tc.$);
The class name is set on Line 2 (MainNav).
Tip: You could save the above javascript in a file called Tc.Module.MainNav.js and included after the TerrificJS Bootstrap.
Conclusion
So, this is who you can integrate and use TerrificJS on your website. Feel free to contact me if you have any questions or want to see more specific examples.
