Include Learn

Include is a JavaScript loading and compressing library that simplifies loading JavaScript file dependencies. You can load files relative to your current file and compress all your application files into one with no extra coding.

After reading this guide, you'll know how to use Include to load scripts and compress your application, while avoiding common problems.

Table of Contents

• How to use
• Script load order
• Working with modes
• Using a setup file

How to Use

1. Download and add to your page.

Download JavaScriptMVC and add a script tag that loads include.js:

<script src="include.js?myapp,development" type="text/javascript"></script>

After the path to include, the src attribute specifies the name of your application and the mode. In this case, the application myapp is loaded in development mode.

2. Include JavaScript files.

Create an application file at 'app/myapp.js'. Application files are where you include JavaScriptMVC plugins and files.

include('javascripts/prototype', 'javascripts/myapplication');

Includes are performed relative to the including file. Files are included last-in-first-out after the current file has been loaded and run.

3. Compress your application.

To compress your application, switch to compress mode by changing the src attribute of your script tag:

<script src="include.js?myapp,compress" type="text/javascript"></script>

After your page loads, a compressed version is presented to you. Create a production file at 'app/myapp_production.js' and copy the text of the compressed collection there.

4. Run in production.

After saving the compressed file, switch to production mode by changing compress to production:

<script src="include.js?myapp,production" type="text/javascript"></script>

Script Load Order

The load order for your scripts follows a consistent last-in first-out order across all browsers. This is the same way the following document.write would work in IE:

document.write('<script type="text/javascript" src="some_script.js"></script>')

An example helps illustrate this.

Script loading dependencies

Working with Modes

Using the include.get_env() function, you can write code that runs only in a certain mode.

if(include.get_env() == 'development')
   Console.log('user clicked self destruct');
else if(include.get_env() == 'production')
   // do something else

Using a setup file

JavaScript files are loaded after the current JavaScript file has been executed, not immediately after include() is called. To load file dependencies, use a setup file that loads dependencies before you load the JavaScript files that need them:

Including dependencies correctly

include('setup');

include('geometry_helpers', 'draw_circle');

// this function is defined in geometry_helpers.js,
// which loaded before this file
Geometry.circle_coordinates(5);

Including dependencies incorrectly

include('draw_circle');

// will be included after library.js is loaded and run
include('geometry_helpers');
// Geometry won't be defined yet, so this will break
Geometry.circle_coordinates(5);

As JavaScript files are run, Include puts their calls to include() on a stack. After the script is completely executed, JavaScript files on the stack are loaded and executed. Thus, as the example above demonstrates, if you write include('dependency') at the top of your JavaScript file, and you write code that depends on dependency.js in the same file, the code will break.

Related Learning

Overview
Include's features, highlights, and a Ruby compressor script.

API
Low level documentation on the Include methods.

TinyMCE Compression Demo
This page demonstrates the ease with which you can compress a complex library and its optional components.

Simple Compression Demo
See compression in action and a description of the compression window's contents.