Using steal steal.use

After installing StealJS, you will have steal/steal.js. This provides the steal function that loads scripts, css, and other modules into your like:

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

})

To use steal effectively, you need to know how to:

• 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 look at a quick example.

Quick Example

The following walks through the steps to create an application that loads a JavaScript and LESS module.

The resulting folder structure will look like:

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

Follow these steps 5:

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)
})

5. 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. 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 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'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 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 map and 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.