JavaScriptMVC Getting Started

From JavaScriptMVC

This guide introduces the most important aspects of JavaScriptMVC by walking through creating a simple Hello World application. Here's what's covered:

JavaScriptMVC in a Nutshell

JavaScriptMVC helps you develop the right way, with:

Organization

Files are logically organized, so you can find what you're looking for quickly.

Here's a snapshot of JavaScriptMVC's application structure:

File Structure

Plugin system

Everything in JavaScriptMVC is a plugin, which provide functionality like Controllers and Views. You include just the ones you need.

Development modes

Modes for each phase of development:

Development - optimized for debugging
Production - loads a compressed file
Test - loads console and application tests

Creating Hello World

This section walks you through writing Hello World after a page loads. The purpose of a controller is to respond to events. You'll use a controller to create the event handler that responds to the document's load event. You'll:

1. Download and update JavaScriptMVC
2. Create an application
3. Generate a controller
4. Include your controller
5. Run your Hello World application

Step 1: Download and update

Download the latest JavaScriptMVC. Unzip the folder on your file system or web server.

A simple JavaScriptMVC application, similar to what you'll create shortly, is running in index.html. You may want to refer to this as a reference.

To update, type:

C:\workspace\HelloWorld>js jmvc\update

Step 2: Create an application

JavaScriptMVC uses generator scripts to assist you in setting up your application's structure and files.

To create your application, open a console window and navigate to your project directory. Run the following command:

C:\workspace\HelloWorld>js jmvc\generate\app hello_world
Generating ... apps/hello_world.js
               apps/hello_world
               apps/hello_world/compress.js
               apps/hello_world/index.html
               apps/hello_world/test.js

Make sure to add new files to your application and test file!

This script has created a basic set of files and saved them to your apps directory. The most important is the application file, which is what JavaScriptMVC applications use to load plugins and other JavaScript files, such as controller, model, and view files.

Use the following script to create a page that loads your application:

C:\workspace\HelloWorld>js jmvc/generate/page hello_world index.html
Generating ... index.html

This script has created a page, index.html, which loads your application file. In the next step, you'll add Hello World functionality.

Step 3: Generate a controller

Controllers are organized collections of event handlers. You'll create one and load it using the application file.

Run the following in your console to generate a controller:

C:\workspace\HelloWorld>js jmvc/generate/controller hello_world
Generating ... controllers/hello_world_controller.js
               test/functional/hello_world_controller_test.js

Note that two files were created: a controller file and a controller test file. Tests are discussed in a later section.

Now you'll add code that will write Hello World once the page has loaded. Paste the following in hello_world_controller.js:

HelloWorldController = MVC.Controller.extend('hello_world',
/* @Static */
{},
/* @Prototype */
{
   load: function(params){
      document.body.innerHTML += "<h1 id='hello'>Hello World</h1>";
   }
});

This sets HelloWorldController to respond to the window's onload event and write Hello World to the page.

Step 4: Include the controller

You need to include hello_world_controller.js in the list of scripts your application loads. To do so, include the file in your application's application file. Add the following to apps/hello_world.js:

include.resources();
include.plugins('controller','view');
 
include(function(){ //runs after prior includes are loaded
  include.models();
  include.controllers('hello_world'); // adds  ../controllers/hello_world_controller.js
  include.views();
});

When the page loads, the application file will load some basic plugins then your controller. You should include all files in this manner.

Step 5: Run it

That's it. You've created a simple Hello World application. Open index.html in a browser.

Hello World

Testing Hello World

The Test plugin allows you to simulate user interactions to comprehensively and easily test your applications. This section will go over testing your simple Hello World application.

Step 1: Turn on test mode

Change the src attribute of the script tag that loads include.js like this:

<script type='text/javascript' src='jmvc/include.js?hello_world,test'></script>

Reload your page. The JavaScriptMVC Console will load in another window:

JavaScriptMVC Console

Step 2: Run the existing tests

Click the Functional tab. Run the test by clicking the play button.

Run Test

When we generated a hello_world_controller, the script also created a hello_world_controller_test in test/functional. The tests simply assert true. Next we'll add a more meaningful test.

Step 3: Create a hello world test

Replace the code in test/functional/hello_world_controller_test.js with the following:

new Test.Controller('hello_world',{
   test_helloworld: function() {
      // check that Hello World has been written
      this.assert_equal('Hello World', document.getElementById('hello').innerHTML);
   }
});

This test asserts Hello World has been inserted into the page correctly. Reload your page and run the test.

Compressing Hello World

There is a large overhead associated with downloading many JavaScript files. JavaScriptMVC stresses never burdening your users with slow downloads. Server side compression makes it simple to compress your code into one file with no extra programming.

Step 1: Compress

To compress your application, run the following command from a console:

C:\workspace\HelloWorld>js apps/hello_world/compress.js
   ../../apps/hello_world.js
   jmvc/plugins/core/setup.js
   jmvc/plugins/lang/standard_helpers.js
   plugins/lang/inflector/inflector.js
   plugins/dom/event/standard.js
   plugins/io/ajax/ajax.js
   plugins/lang/class/setup.js

When you generated your application, apps/hello_world/compress.js was automatically created. The command above loaded this script, which loaded all your application files in the Rhino JavaScript runtime, compressed them, and saved them in apps/hello_world/production.js.

Verify that production.js was created.

Step 2: Switch to production mode

Turn on production mode by changing the part of the src tag in index.html that says test to production like this:

<script type='text/javascript' src='jmvc/include.js?hello_world,production'></script>

Step 3: Reload and verify

Reload your page. Only two JavaScript files will load: include.js and production.js. Not bad considering 28 files are loaded in development mode.

Production files

Documenting Hello World

Documentation is an important step in creating maintainable code. It's often too burdensome on developers so it becomes a neglected step. JavaScriptMVC creates documentation for you automatically from your comments.

Step 1: Add comments

Add the following comments to controllers/hello_world_controller.js:

/**
 * A Controller that prints "Hello World" when the page loads. 
 */
HelloWorldController = MVC.Controller.extend('hello_world',
/* @Static */
{},
/* @Prototype */
{
 /**
  * Onload handler for the page.  Writes "Hello World" to the body.
  * @param {Object} params Contains element and event objects.
  */
  load: function(params){
    document.body.innerHTML += "<h1 id='hello'>Hello World</h1>";
  }
});

The documentation generator will create a formatted HTML page documenting the HelloWorldController class.

Step 2: Generate documentation

You may have noticed when you compressed your application, documentation was generated. Run the compressor script again to generate documentation for the HelloWorldController class:

C:\workspace\HelloWorld>js apps\hello_world\compress.js

You'll see the following in the printed output:

docs for ../../controllers/hello_world_controller.js
Generated docs.

Step 3: View documentation

Notice the previously empty docs directory is now filled with HTML files. Open docs/hello_world.html and click HelloWorldController:

Documentation

Next steps

In the context of this trivial application, you've been exposed to major tenets of JavaScriptMVC: code separation, testing, compression, and documentation. This is pretty cool! Look at how simply you went from nothing to a compressed and tested application.

There is a lot more to be learned! JavaScriptMVC lets you work together with jQuery, Prototype, and other libraries, add error notification, separate your presentation markup, and easily access web services.

For more information consult the following resources:

JavaScript's Rules