diff options
Diffstat (limited to 'src/Angular.js')
| -rw-r--r-- | src/Angular.js | 191 |
1 files changed, 188 insertions, 3 deletions
diff --git a/src/Angular.js b/src/Angular.js index a1477e35..c40a7c67 100644 --- a/src/Angular.js +++ b/src/Angular.js @@ -1,3 +1,12 @@ +/** + * @ngdoc overview + * @name angular + * @namespace Namespace for angular. + * @description + * Hello world! + * + * @example + */ //////////////////////////////////// if (typeof document.getAttribute == $undefined) @@ -91,6 +100,67 @@ var _undefined = undefined, angular = window[$angular] || (window[$angular] = {}), angularTextMarkup = extensionMap(angular, 'markup'), angularAttrMarkup = extensionMap(angular, 'attrMarkup'), + /** + * @ngdoc overview + * @name angular.directive + * @namespace Namespace for all directives. + * @description + * A directive is an XML attribute that you can use in an existing HTML + * element type or in a DOM element type that you create using + * `angular.widget`, to modify that element's properties. You can use + * any number of directives per element. + * + * For example, you can add the ng:bind directive as an attribute of an + * HTML span element, as in `<span ng:bind="1+2"></span>`. + * How does this work? The compiler passes the attribute value `1+2` + * to the ng:bind extension, which in turn tells the Scope to watch + * that expression and report changes. On any change it sets the span + * text to the expression value. + * + * Here's how to define ng:bind: + * <pre> + angular.directive('ng:bind', function(expression, compiledElement) { + var compiler = this; + return function(linkElement) { + var currentScope = this; + currentScope.$watch(expression, function(value) { + linkElement.text(value); + }); + }; + }); + * </pre> + * + * ## Directive vs. Attribute Widget + * Both attribute widgets and directives can compile a DOM element + * attribute. So why have two different ways to do the same thing? + * The answer is that order matters, but you have no control over + * the order in which attributes are read. To solve this we + * apply attribute widget before the directive. + * + * For example, consider this piece of HTML, which uses the + * directives `ng:repeat`, `ng:init`, and `ng:bind`: + * <pre> + <ul ng:init="people=['mike', 'mary']"> + <li ng:repeat="person in people" ng:init="a=a+1" ng:bind="person"></li> + </ul> + * </pre> + * + * Notice that the order of execution matters here. We need to + * execute ng:repeat before we run the `ng:init` and `ng:bind` + * on the `<li/>;`. This is because we want to run the + * `ng:init="a=a+1` and `ng:bind="person"` once for each + * person in people. We could not have used directive to + * create this template because attributes are read in an + * unspecified order and there is no way of guaranteeing + * that the repeater attribute would execute first. Using + * the `ng:repeat` attribute directive ensures that we can + * transform the DOM element into a template. + * + * Widgets run before directives. Widgets are expected to + * manipulate the DOM whereas directives are not expected + * to manipulate the DOM, and they run last. + * + */ angularDirective = extensionMap(angular, 'directive'), /** @@ -332,7 +402,7 @@ var _undefined = undefined, * The formatters are responsible for translating user readable text in an input widget to a * data model stored in an application. * - * # Writting your own Fromatter + * # Writting your own Formatter * Writing your own formatter is easy. Just register a pair of JavaScript functions with * `angular.formatter`. One function for parsing user input text to the stored form, * and one for formatting the stored data to user-visible text. @@ -391,7 +461,7 @@ var _undefined = undefined, * * * @scenario - * it('should store reverse', function(){ + * iit('should store reverse', function(){ * expect(element('.doc-example input:first').val()).toEqual('angular'); * expect(element('.doc-example input:last').val()).toEqual('RALUGNA'); * @@ -399,7 +469,7 @@ var _undefined = undefined, * $document.elements('.doc-example input:last').val('XYZ').trigger('change'); * done(); * }); - * expect(element('input:first').val()).toEqual('zyx'); + * expect(element('.doc-example input:first').val()).toEqual('zyx'); * }); */ angularFormatter = extensionMap(angular, 'formatter'), @@ -767,6 +837,121 @@ function toKeyValue(obj) { return parts.length ? parts.join('&') : ''; } +/** + * @ngdoc directive + * @name angular.directive.ng:autobind + * @element script + * + * @description + * This section explains how to bootstrap your application to + * the <angular/> environment using either the + * `angular-x.x.x.js` or `angular-x.x.x.min.js` script. + * + * ## The bootstrap code + * Note that there are two versions of the bootstrap code that you can use: + * + * * `angular-x.x.x.js` - this file is unobfuscated, uncompressed, and thus + * human-readable. Note that despite the name of the file, there is + * no additional functionality built in to help you debug your + * application; it has the prefix debug because you can read + * the source code. + * * `angular-x.x.x.min.js` - this is a compressed and obfuscated version + * of `angular-x.x.x.js`. You might want to use this version if you + * want to load a smaller but functionally equivalent version of the + * code in your application. Note: this minified version was created + * using the Closure Compiler. + * + * + * ## Auto bind using: <tt>ng:autobind</tt> + * 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: + * + * <pre> + <!doctype html> + <html xmlns:ng="http://angularjs.org"> + <head> + <script type="text/javascript" ng:autobind + src="http://code.angularjs.org/angular-0.9.3.min.js"></script> + </head> + <body> + Hello {{'world'}}! + </body> + </html> + * </pre> + * + * The `ng:autobind` attribute tells <angular/> to compile and manage + * the whole HTML document. The compilation occurs in the page's + * `onLoad` handler. Note that you don't need to explicitly add an + * `onLoad` event; auto bind mode takes care of all the magic for you. + * + * # Manual Bind + * Using autobind mode is a handy way to start using <angular/>, but + * advanced users who want more control over the initialization process + * might prefer to use manual bind mode instead. + * + * The best way to get started with manual bind mode 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. + * + * <pre> + <!doctype html> + <html xmlns:ng="http://angularjs.org"> + <head> + <script type="text/javascript" ng:autobind + src="http://code.angularjs.org/angular-0.9.3.min.js"></script> + <script type="text/javascript"> + (function(window, previousOnLoad){ + window.onload = function(){ + try { (previousOnLoad||angular.noop)(); } catch(e) {} + angular.compile(window.document).$init(); + }; + })(window, window.onload); + </script> + </head> + <body> + Hello {{'World'}}! + </body> + </html> + * </pre> + * + * This is the sequence that your code should follow if you're writing + * your own manual binding code: + * + * * After the page is loaded, find the root of the HTML template, + * which is typically the root of the document. + * * Run the HTML compiler, which converts the templates into an + * executable, bi-directionally bound application. + * + * #XML Namespace + * *IMPORTANT:* When using <angular/> you must declare the ng namespace + * using the xmlsn tag. If you don't declare the namespace, + * Internet Explorer does not render widgets properly. + * + * <pre> + * <html xmlns:ng="http://angularjs.org"> + * </pre> + * + * # 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: + * + * <pre> + * <html xmlns:ng="http://angularjs.org" xmlns:my="http://mydomain.com"> + * </pre> + * + * # 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. + * + */ function angularInit(config){ if (config.autobind) { // TODO default to the source of angular.js |