steal is a function that loads scripts, css, and other resources into your application.

steal(FILE_or_FUNCTION, ...)

Quick Walkthrough

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

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

Then, start loading things and using them like:

 steal('myapp/tabs.js',
       'myapp/slider.js', 
       'myapp/style.css',function(){
 
    // tabs and slider have loaded 
    $('#tabs').tabs();
    $('#slider').slider()
 })

Make sure your widgets load their dependencies too:

 // myapp/tabs.js
 steal('jquery', function(){
   $.fn.tabs = function(){
    ...
   }
 })

Examples:

 // Loads ROOT/jquery/controller/controller.js
 steal('jquery/controller')
 steal('jquery/controller/controller.js')
 
 // Loads coffee script type and a coffee file relative to
 // the current file
 steal('steal/coffee').then('./mycoffee.coffee')
 
 // Load 2 files and dependencies in parallel and
 // callback when both have completed
 steal('jquery/controller','jquery/model', function(){
   // $.Controller and $.Model are available
 })
 
 // Loads a coffee script with a non-standard extension (cf)
 // relative to the current page and instructs the build
 // system to not package it (but it will still be loaded).
 steal({
    src: "./foo.cf",
    packaged: false,
    type: "coffee"
  })

The following is a longer walkthrough of how to install
and use steal:

Adding steal to a page

After installing StealJS (or JavaScriptMVC),
find the steal folder with
steal/steal.js.

To use steal, add a script tag
to steal/steal.js to your
html pages.

This walkthrough assumes you have the steal script in public/steal/steal.js and a directory structure like:

@codestart text
/public
/steal
/pages
myapp.html
/myapp
myapp.js
jquery.js
jquery.ui.tabs.js
@codeend

To use steal in public/pages/myapp.html,
add a script tag in myapp.html:

@codestart html
<script type='text/javascript'
src='../steal/steal.js'>
</script>
@codeend

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

Loading the First Script

Once steal has been added to your page, it's time
to load scripts. We want to load myapp.js
and have it load jquery.js and
jquery.ui.tabs.js.

By default, steal likes your scripts
to be within in the [steal.static.root steal.root] folder. The [steal.root] the
folder contains the steal folder. In this example,
it is the public folder.

To load myapp/myapp.js, we have two options:

Add a script tag

Add a script tag after the steal
script that 'steals' myapp.js like:

@codestart html
<script type='text/javascript'>
steal('myapp/myapp.js')
</script>
@codeend

Add the script parameter

The most common (and shortest) way to load myapp.js
is to add the script path to the steal script's src after in the
query params. So, instead of adding a script, we change
the steal script from:

@codestart html
<script type='text/javascript'
src='../steal/steal.js'>
</script>
@codeend

To

@codestart html
<script type='text/javascript'
src='../steal/steal.js?myapp/myapp.js'>
</script>
@codeend

PRO TIP: You can also just add
?myapp to the query string.

Loading Scripts

We want to load jquery.js and
jquery.ui.tabs.js into the page and then
add then create a tabs widget. First we need to load
jquery.js.

By default, steal loads script relative to [steal.root]. To
load myapp/jquery.js we can the following to
myapp.js:

 steal('myapp/jquery.js');

But, we can also load relative to myapp.js like:

 steal('./jquery.js');

Next, we need to load jquery.ui.tabs.js. You
might expect something like:

 steal('./jquery.js','./jquery.ui.tabs.js')

to work. But there are two problems / complications:

  • steal loads scripts in parallel and runs out of order
  • jquery.ui.tabs.js depends on jQuery being loaded

This means that steal might load jquery.ui.tabs.js
before jquery.js. But this is easily fixed.

[steal.static.then] waits until all previous scripts have loaded and
run before loading scripts after it. We can load jquery.ui.tabs.js
after jquery.js like:

 steal('./jquery.js').then('./jquery.ui.tabs.js')

Finally, we need to add tabs to the page after
the tabs's widget has loaded. We can add a callback function to
steal that will get called when all previous scripts have finished
loading:

 steal('./jquery.js').then('./jquery.ui.tabs.js', function($){
   $('#tabs').tabs();
 })

Other Info

Exclude Code Blocks From Production

To exclude code blocks from being included in
production builds, add the following around
the code blocks.

 //!steal-remove-start
     code to be removed at build
 //!steal-remove-end

Lookup Paths

By default steal loads resources relative
to [steal.static.root steal.root]. For example, the following
loads foo.js in steal.root:

 steal('foo.js'); // loads //foo.js

This is the same as writing:

 steal('//foo.js');

Steal uses '//' to designate the [steal.static.root steal.root]
folder.

To load relative to the current file, add "./" or
"../":

 steal("./bar.js","../folder/zed.js");

Often, scripts can be found in a folder within the same
name. For example, [jQuery.Controller $.Controller] is
in //jquery/controller/controller.js. For convience,
if steal is provided a path without an extension like:

 steal('FOLDER/PLUGIN');

It is the same as writing:

 steal('FOLDER/PLUGIN/PLUGIN.js')

This means that //jquery/controller/controller.js
can be loaded like:

  steal('jquery/controller')

Types

steal can load resources other than JavaScript.

@constructor

Loads resources specified by each argument. By default, resources
are loaded in parallel and run in any order.

@param {String|Function|Object} resource...

Each argument specifies a resource. Resources can
be given as a:

Object

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

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

The available options are:

  • src {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.

  • 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'.

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

String

Specifies src of the resource. For example:

   steal('./file.js')

Is the same as calling:

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

Function

A callback function that runs when all previous steals
have completed.

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

@return {steal} the steal object for chaining
/

Comments

comments powered by Disqus