If you think of JavaScript as the ugly duckling of programming languages, think again! It got a bad rap in the earlier days of the web because developers knew enough just to get by but didn’t really respect it like they did Java, PHP or .Net. Like other well-known and heavily used languages, JavaScript contains various data types (String, Boolean, Number, etc.), objects and functions, and it is even capable of inheritance. Unfortunately, that functionality is often overlooked, and many developers seem to implement it as an afterthought: “Oh, we need to add some neat jQuery effects over there? I’ll just throw some inline JavaScript here.” That kind of implementation perpetuates a stereotype that JavaScript code is unorganized and difficult to maintain, but it doesn’t have to be! I’m going to show you how easy it is to maintain and organize your code base by packaging your JavaScript classes into a single file to be included with your website.
There are a few things to cover before we jump into code:
- JavaScript Framework – Mootools is my framework of choice, but you can use whatever JavaScript framework you’d like.
- Classes – Because I see JavaScript as another programming language that I respect (and is capable of object-oriented-like design), I write classes for EVERYTHING. Don’t think of your JavaScript code as something you use once and throw away. Write your code to be generic enough to be reused wherever it’s placed. Object-oriented design is great for this! Mootools makes object-oriented design easy to do, so this point reinforces the point above.
- Class Files – Just like you’d organize your PHP to contain one class per file, I do the exact same thing with JavaScript. Note: Each of the class files in the example below uses the class name appended with
.js. - Namespacing – I will be organizing my classes in a way that will only add a single property — PT — to the global namespace. I won’t get into the details of namespacing in this blog because I’m sure you’re already thinking, “The code! The code! Get on with it!” You can namespace whatever is right for your situation.
For this example, our classes will be food-themed because … well … I enjoy food. Let’s get started by creating our base object:
/* --- name: PT description: The base class for all the custom classes authors: [Philip Thompson] provides: [PT] ... */ var PT = {};
We now have an empty object from which we’ll build all of our classes. We’ll go I will go into more details later about the comment section, but let’s build our first class: PT.Ham.
/* --- name: PT.Ham description: The ham class authors: [Philip Thompson] requires: [/PT] provides: [PT.Ham] ... */ (function() { PT.Ham = new Class({ // Custom code here... }); }());
As I mentioned in point three (above), PT.Ham should be saved in the file named PT.Ham.js. When we create second class, PT.Pineapple, we’ll store it in PT.Pineapple.js:
/* --- name: PT.Pineapple description: The pineapple class authors: [Philip Thompson] requires: [/PT] provides: [PT.Pineapple] ... */ (function() { PT.Pineapple = new Class({ // Custom code here... }); }());
Our final class for this example will be PT.Pizza (I’ll let you guess the name of the file where PT.Pizza lives). Our PT.Pizza class will require that PT, PT.Ham and PT.Pineapple be present.
/* --- name: PT.Pizza description: The pizza class authors: [Philip Thompson] requires: [/PT, /PT.Ham, /PT.Pineapple] provides: [PT.Pizza] ... */ (function() { PT.Pizza = new Class({ // Custom code here that uses PT.Ham and PT.Pineapple... }); }());
Before we go any further, let’s check out the comments we include above each of the classes. The comments are formatted for YAML — YAML Ain’t Markup Language (you gotta love recursive acronyms). These comments allow our parser to determine how our classes are related, and they help resolve dependencies. YAML’s pretty easy to learn and you only need to know a few basic features to use it. The YAML comments in this example are essential for our JavaScript package-manager — Packager. I won’t go into all the details about Packager, but simply mention a few commands that we’ll need to build our single JavaScript file.
In addition to the YAML comments in each of the class files, we also need to create a YAML file that will organize our code. This file — package.yml for this example — is used to load our separate JavaScript classes:
name: "PT" description: "Provides our fancy PT classes" authors: "[Philip Thompson]" version: "1.0.0" sources: - js/PT.js - js/PT.Ham.js - js/PT.Pineapple.js - js/PT.Pizza.js
package.yml shows that all of our PT* files are located in the js directory, one directory up from the package.yml file. Some of the properties in the YAML file are optional, and you can add much more detail if you’d like, but this will get the job done for our purposes.
Now we’re ready to turn back to Packager to build our packaged file. Packager includes an option to use PHP, but we’re just going to do it command-line. First, we need to register the new package (package.yml) we created for PT. If our JavaScript files are located in /path/to/web/directory/js, the package.yml file is in /path/to/web/directory:
./packager register /path/to/web/directory
This finds our package.yml file and registers our PT package. Now that we have our package registered, we can build it:
./packager build * > /path/to/web/directory/js/PT.all.js
The Packager sees that our PT package is registered, so it looks at each of the individual class files to build a single large file. In the comments of each of the class files, it determines if there are dependencies and warns you if any are not found.
It might seem like a lot of work when it’s written out like this, but I can assure you that when you go through the process, it takes no time at all. The huge benefit of packaging our JavaScript is evident as soon as you start incorporating those JavaScript classes into your website … Because we have built all of our class files into a single file, we don’t need to include each of the individual JavaScript files into our website (much less include the inline JavaScript declarations that make you cringe). To streamline your implementation even further if you’re using your JavaScript package in a production deployment, I recommend that you “minify” your code as well.
See … Organized code is no longer just for server-side only languages. Treat your JavaScript kindly, and it will be your friend!
Happy coding!
-Philip