Execution

Bonsai movies can be executed in two execution contexts (we call them “runner contexts”):

Note: The runner context has limited access to browser functionality (e.g. no DOM access) because in most cases the Bonsai code is executed in a worker. Therefore you are limited to use the provided Bonsai API and the normal JS functions that are provided for a worker (see Functions available for workers on MDN for details). If you want to pass initial data to the runner context you can read about that at the bottom of this page or if you want to dynamically manipulate the DOM through Bonsai you should have a look at the Communication overview.

The built version of Bonsai is taking care to select the best approach for a particular browser (determined through feature detection):

So if you use the built version of Bonsai (e.g. from CDNJS), it will take care of the right strategy for you:

<script src="http://cdnjs.cloudflare.com/ajax/libs/bonsai/0.4/bonsai.min.js"></script>
<div id="movie"></div>
<script>
  bonsai.run(document.getElementById('movie'), 'movie.js');
</script>

There are cases where you want to force the Bonsai runner context to be the iFrame. You can achieve this behaviour like so:

bonsai.setup({
  runnerContext: bonsai.IframeRunnerContext
}).run(stageNode, 'movie.js');

There are some environments where we can’t automatically create the worker environment through a Blob- or Data-URI (e.g. iOS 5 and Safari 5). In case you just want to use the worker context and if you can accept to exclude browsers that don’t support web workers you can limit the execution to the worker context and additionally feed it the original bonsai.js as runner URL to reach all browsers that have worker support (Note: you need to load bonsai.js from the same domain, where the original page is served from, to avoid cross domain issues):

bonsai.setup({
  runnerContext: bonsai.WorkerRunnerContext,
  runnerUrl: 'bonsai.js'
}).run(stageNode, 'movie.js');

Here’s an overview of how Bonsai operates:

Bonsai separated architecture, showing parent page and runner-context where the actual bonsai movie is run

As seen before, Bonsai will reveal itself as simply bonsai on the parent page. The actual API (e.g. Shape, stage.addChild() etc.) will only be available within the specified context. The API revealed on the parent page allows loading of movies, like so:

bonsai.run(
  document.getElementById('movie'),
  'path/to/my_movie.js',
  {
    width: 500,
    height: 400
  }
);

Options you can pass to bonsai.run() include:

There are three available signatures for loading/executing a single movie:

bonsai.run(element, movieUrl, { /* options */ });
bonsai.run(element, { url: movieUrl /*, ... other options */ });
bonsai.run(element, { code: '' /* string|function */ /*, ... other options */ });

You can also pass initial data through bonsai.run to the runner context:

bonsai.run(
  document.getElementById('movie'),
  {
    url: 'movie.js',
    initialData1: { bonsai: 'tree' },
    initialData2: true,
    initialData3: 'bonsaiiiii'
  }
);

Which then can be accessed from the runner context (movie.js or JS code that was passed within code) like this:

console.log(stage.options.initialData1); // { bonsai: 'tree'}
console.log(stage.options.initialData2); // true
console.log(stage.options.initialData3); // 'bonsaiiiii'
console.log(stage.options.url); // 'movie.js'

For dynamically passing data from your page to the runner context or sending data from it to the page you should have a look at Communication overview.