steal.md

@class steal @parent stealjs

steal(moduleIds..., definition(modules...)) loads scripts, css, and other modules into your application. For example:

steal('jquery','can',function($, can){
  
})

To use steal effectively, there's four things you need to know how to do:

• Add steal.js to your page
• Configure steal's behavior
• Load modules
• Return module values

We will go into each of these in detail, but first lets do the "hello world" of steal:

Quick Overview

To create a JavaScript and LESS module for use in myapp assuming a folder structure like:

ROOT/
  steal/
    steal.js
    ...
  myapp/
    myapp.js
    myapp.less
    mymodule.js
    index.html
  stealconfig.js

Follow these steps:

0. Create myapp, its contents, and stealconfig.js.

1. Add a script tag to index.html that loads steal/steal.js and add the path to the first file to load in the query string like:

<script src='../steal/steal.js?myapp/myapp.js'>
</script>

2. In stealconfig.js, configure steal to load the less engine for any modules ending in .less like:

steal.config({
  ext: {
    less: "steal/less/less.js"
  }
})

3. Add the following to mymodule.js:

steal(function(){
  return function(element){
    element.innerHTML = "Hello World"
    element.className = "welcome"
  }
})

myapp/mymodule.js's module value is a function that sets an element's contents and changes its class attribute to "welcome".

Add the following to myapp.less:

@@dark #228022;
.welcome {
  color: @dark;
}

myapp/myapp.less adds a .welcome style to the app.

4. Add the following to myapp/myapp.js:

steal("./mymodule.js","./myapp.less",function(mymodule){
  mymodule(document.body)
})

Open index.html, you should find Hello World. Read on to understand setting up steal in detail.

Add steal.js to your page

The first step to using steal is to add steal/steal.js to your page.

<script src='../public/steal/steal.js'>
</script>

PRO TIP: Bottom load your scripts. It will increase your application's percieved response time.

With this, you can start stealing modules. For example, you could load jQuery from a CDN in a following script tag like:

<script src='../public/steal/steal.js'>
</script>
<script>
steal('http://cdn.com/jquery-1.8.3.js',function(){
   $
})
</script>

The folder that contains the steal folder is the [rootfolder root folder]. By default, all modules are loaded from the root folder unless they start with:

• "http://" or "https://" like "http://foo.com/bar.js"
• "/" like "/bar.js"

So the following would load public/component.js:

<script>
steal('http://cdn.com/jquery-1.8.3.js',
  'component.js',
  function(){

})
</script>

Although, your HTML pages that load steal can exist anywhere can be served up dynamically, it's best to have all your JavaScript, CSS, and other static resources in the [rootfolder root folder].

But steal allows you to configure pretty much everything as we will see ...

Configure steal's behavior

[steal.config](configOptions) allows you to change the behavior of how steal loads modules. steal.config allows you to set rules that:

• Apply for all modules. (ex: changing the location of the root folder)
• Apply for a single moduleId. (ex: 'steal/dev/dev.js' should not be added to production)
• Apply to startup. (_ex: load myapp/myapp.js as the first JS module)

You can find a full list of options in [steal.config steal.config's docs], but the most common configuration options are:

• startFile - the first moduleId to load. Example: "myapp/myapp.js".
• env - the environment the page is running in: "development" or "production". By default, env is development.

For any application that you intend to [steal.build build], startFile and env need to be set.

You can set configOptions in a variety ways:

Set startFile and env in the script tag

You can set startFile and env the queryparams of steal like:

<script src='../steal/steal.js?STARTFILE,ENV'>
</script>

For example:

<script src='../steal/steal.js?cookbook,production'>
</script>

If you load steal/steal.production.js the environment defaults to production:

<script src='../steal/steal.production.js?cookbook'>
</script>

Call steal.config(stealConfig)

After steal.js is loaded and run, you can call steal.config anywhere in the application. However, after steal.js loads, it automatically loads stealconfig.js before it loads anything else. stealconfig.js is the best place to configure settings that should be applied to all projects.

A steal object that exists before steal.js is loaded

If a steal object exists before steal.js is loaded, steal will internally call steal.config with that object. For example:

<script>
steal = {
  executed: "myapp/production.css"
}
</script>
<script src='../steal/steal.production.js,myapp'>
</script>

Load modules

Use steal(ids...) to load dependent modules. Ids might look like:

// in myapp/myapp.js
steal('components/item',
      'person.js',
      './view.ejs')

Steal uses [steal.id] to convert the id passed to steal into a moduleId. It then uses [steal.idToUri] to convert that moduleId into a URI to load the resource.

The behavior of [steal.id] and [steal.idToUri] can be configured by steal.config's [steal.config.map map] and [steal.config.paths paths] options. But the default behavior is as follows:

• "components/item" is found in ROOT/components/item/item.js
• "person.js" is found in ROOT/person.js
• "./view.ejs" is found in ROOT/myapp/view.ejs

It is possible to use:

• a url like: "http://cdn.com/foo.js"
• a path relative to the domain like: "/foo.js"

But, we STRONGLY encourage you to use moduleId's and [steal.config] to adjust the lookup path for resources outside stealroot.

Return module values

After the optional list of moduleIds, you can pass steal a "definition" function. For example:

// in myapp/myapp.js
steal('components/item',
      'person.js',
      './view.ejs', 
      
      function(item, Person, viewEJS){
      
          return MODULEVALUE;
      
      })

The "definition" function gets called with each dependent module's value and can optionally return a module value of its own. Your code goes in the definition function.

If a module doesn't return a value, undefined is passed to the definition function.

@param {String|Object} [moduleIds...]

Each argument specifies a module. Modules can be given as a:

Object

An object that specifies the loading and build behavior of a resource.

 steal({
   id: "myfile.cf",
   type: "coffee",
   packaged: true,
   unique: true,
   ignore: false,
   waits: false
 })

The available options are:

• id {String} - the path to the resource.

• waits {Boolean default=false} - true the resource should wait for prior steals to load and run. False if the resource should load and run in parallel. This defaults to true for functions.

• unique {Boolean default=true} - true if this is a unique resource that 'owns' this url. This is true for files, false for functions.

• ignore {Boolean default=false} - true if this resource should not be built into a production file and not loaded in production. This is great for script that should only be available in development mode. This script is loaded during compression, but not added to the bundled script.

• packaged {Boolean default=true} - true if the script should be built into the production file. false if the script should not be built into the production file, but still loaded. This is useful for loading 'packages'. This script is loaded during compression, but not added to the bundled script. The difference with ignore is packaged still steals this file while production mode, from an external script.

• type {String default="js"} - the type of the resource. This is typically inferred from the src.

String

Specifies id of a module. For example:

  steal('./file.js')

Is the same as calling:

  steal({id: './file.js'})

@param {Function} [definition(moduleValues...)]

A "definition" function that runs when all previous steals have completed.

steal('jquery', 'foo',function($, foo){
  // jquery and foo have finished loading
  // and running
})

@return {steal} the steal object for chaining