angular.directive.ng:autobind

Work in Progress This page is currently being revised. It might be incomplete or contain inaccuracies.

Description

This section explains how to bootstrap your application with angular, using either the angular javascript file, or manually.

Auto-bootstrap with ng:autobind

The simplest way to get an <angular/> application up and running is by inserting a script tag in your HTML file that bootstraps the http://code.angularjs.org/angular-x.x.x.min.js code and uses the special ng:autobind attribute, like in this snippet of HTML:

    <!doctype html>
    <html xmlns:ng="http://angularjs.org">
     <head>
      <script type="text/javascript" src="http://code.angularjs.org/angular-0.9.3.min.js"
              ng:autobind></script>
     </head>
     <body>
       Hello {{'world'}}!
     </body>
    </html>

The ng:autobind attribute without any value tells angular to compile and manage the whole HTML document. The compilation occurs as soon as the document is ready for DOM manipulation. Note that you don't need to explicitly add an onLoad event handler; auto bind mode takes care of all the work for you.

In order to compile only a part of the document, specify the id of the element that should be compiled as the value of the ng:autobind attribute, e.g. ng:autobind="angularContent".

Auto-bootstrap with #autobind

In rare cases when you can't define the ng namespace before the script tag (e.g. in some CMS systems, etc), it is possible to auto-bootstrap angular by appending #autobind to the script src URL, like in this snippet:

    <!doctype html>
    <html>
     <head>
      <script type="text/javascript"
              src="http://code.angularjs.org/angular-0.9.3.min.js#autobind"></script>
     </head>
     <body>
       <div xmlns:ng="http://angularjs.org">
         Hello {{'world'}}!
       </div>
     </body>
    </html>

In this case it's the #autobind URL fragment that tells angular to auto-bootstrap.

Similarly to ng:autobind, you can specify an element id that should be exclusively targeted for compilation as the value of the #autobind, e.g. #autobind=angularContent.

Filename Restrictions for Auto-bootstrap

In order for us to find the auto-bootstrap script attribute or URL fragment, the value of the script src attribute that loads angular script must match one of these naming conventions:

Optionally, any of the filename format above can be prepended with relative or absolute URL that ends with /.

Manual Bootstrap

Using auto-bootstrap is a handy way to start using <angular/>, but advanced users who want more control over the initialization process might prefer to use manual bootstrap instead.

The best way to get started with manual bootstraping is to look at the magic behind ng:autobind by writing out each step of the autobind process explicitly. Note that the following code is equivalent to the code in the previous section.

    <!doctype html>
    <html xmlns:ng="http://angularjs.org">
     <head>
      <script type="text/javascript" src="http://code.angularjs.org/angular-0.9.3.min.js"
              ng:autobind></script>
      <script type="text/javascript">
       (angular.element(document).ready(function() {
         angular.compile(document)();
       })(document);
      </script>
     </head>
     <body>
       Hello {{'World'}}!
     </body>
    </html>

This is the sequence that your code should follow if you're bootstrapping angular on your own:

XML Namespace

IMPORTANT: When using <angular/> you must declare the ng namespace using the xmlns tag. If you don't declare the namespace, Internet Explorer does not render widgets properly.

<html xmlns:ng="http://angularjs.org">

Create your own namespace

If you want to define your own widgets, you must create your own namespace and use that namespace to form the fully qualified widget name. For example, you could map the alias my to your domain and create a widget called my:widget. To create your own namespace, simply add another xmlsn tag to your page, create an alias, and set it to your unique domain:

<html xmlns:ng="http://angularjs.org" xmlns:my="http://mydomain.com">

Global Object

The <angular/> script creates a single global variable angular in the global namespace. All APIs are bound to fields of this global object.

Usage

<script ng:autobind>
   ...
</script>