From c669abcfb6a481b14b47153f1d6ce5eec2421342 Mon Sep 17 00:00:00 2001 From: naomi black Date: Fri, 21 Mar 2014 12:16:34 -0700 Subject: [PATCH] chore(docs): Basic descriptions for package libraries --- lib/angular.dart | 27 ++++++- lib/animate/module.dart | 34 ++++---- lib/bootstrap.dart | 128 ++++++++++++++++-------------- lib/directive/module.dart | 9 +++ lib/filter/module.dart | 9 +++ lib/mock/module.dart | 13 +++ lib/perf/module.dart | 13 +++ scripts/generate-documentation.sh | 1 - 8 files changed, 152 insertions(+), 82 deletions(-) diff --git a/lib/angular.dart b/lib/angular.dart index 136a01815..db84b4a70 100644 --- a/lib/angular.dart +++ b/lib/angular.dart @@ -1,10 +1,31 @@ /** - * Angular is a framework for building single page web applications. + * Core functionality for angular.dart, a web framework for Dart. + * + * + * You must import the angular library to use it with Dart, like so: + * + * import 'package:angular/angular.dart'; + * + * The angular.dart library includes Angular's Directive and Filter classes: + * + * - [angular.directive](#angular/angular-directive) lists all the basic directives + * - [angular.filter] (#angular/angular-filter) lists all the basic filters + * + * You might also want to optionally import the following Angular libraries: + * + * - [angular.animate](#angular/angular-animate) supports CSS animations that modify the + * lifecycle of a DOM + * element + * - [angular.mock](#angular/angular-mock) provides classes and utilities for testing and + * prototyping + * - [angular.perf](#angular/angular-perf) provides classes to help evaluate performance in your + * app + * * * Further reading: * - * - AngularJS [Overview](http://www.angularjs.org) - * - [Tutorial](https://github.com/angular/angular.dart.tutorial/wiki) + * - AngularDart [Overview](http://www.angulardart.org) + * - [Tutorial](https://angulardart.org/tutorial/) * - [Mailing List](http://groups.google.com/d/forum/angular-dart?hl=en) * */ diff --git a/lib/animate/module.dart b/lib/animate/module.dart index 3560a1371..756cd0fc2 100644 --- a/lib/animate/module.dart +++ b/lib/animate/module.dart @@ -1,16 +1,16 @@ /** - * Css animation and dom lifecycle management for Angular. + * CSS animation and DOM lifecycle management for AngularDart apps. * - * The [animate] library makes it easier to build animations that affect the - * lifecycle of dom elements. A useful example of this is animating the - * removal of an element from the dom. In order to do this ideally the + * The [angular.animate](#angular/angular-animate) library makes it easier to build animations + * that affect the lifecycle of DOM elements. A useful example of this is animating the + * removal of an element from the DOM. In order to do this ideally the * operation should immediatly execute and manipulate the data model, - * and the framework should handle the actual remove of the dom element once + * and the framework should handle the actual remove of the DOM element once * the animation complets. This ensures that the logic and model of the * application is seperated so that the state of the model can be reasoned * about without having to wory about future modifications of the model. * This library uses computed css styles to calculate the total duration - * of an animation and handles the addition, removal, and modification of dom + * of an animation and handles the addition, removal, and modification of DOM * elements for block level directives such as `ng-if`, `ng-repeat`, * `ng-hide`, and more. * @@ -19,30 +19,30 @@ * var module = new Module() * ..install(new NgAnimateModule()); * - * Once the module has been installed, all block level dom manipulations will + * Once the module has been installed, all block level DOM manipulations will * be routed through the [CssAnimate] class instead of the * default [NgAnimate] implementation. This will, in turn, * perform the tracking, manipulation, and computation for animations. * * As an example of how this works, lets walk through what happens whan an - * element is added to the dom. The [CssAnimate] implementation will add the - * `.ng-enter` class to new dom elements when they are inserted into the dom + * element is added to the DOM. The [CssAnimate] implementation will add the + * `.ng-enter` class to new DOM elements when they are inserted into the DOM * by a directive and will read the computed style. If there is a * transition or keyframe animation, that animation duration will be read, * and the animation will be performed. The `.ng-enter-active` class will be - * added to the dom element to set the target state for transition based + * added to the DOM element to set the target state for transition based * animations. When the animation is complete (determined by the * precomputed duration) the `.ng-enter` and `.ng-enter-active` classes - * will be removed from the dom element. + * will be removed from the DOM element. * - * When removing elements from the dom, a simliar pattern is followed. The + * When removing elements from the DOM, a simliar pattern is followed. The * `.ng-leave` class will be added to an element, the transition and / or * keyframe animation duration will be computed, and if it is non-zero the * animation will be run by adding the `.ng-leave-active` class. When * the animation completes, the element will be physically removed from the - * dom. + * DOM. * - * The same set of steps is run for each of the following types of dom + * The same set of steps is run for each of the following types of DOM * manipulation: * * * `.ng-enter` @@ -75,7 +75,7 @@ * `ctrl.visible` property goes from `true` to `false`. * * The [CssAnimate] will also do optimizations on running animations by - * preventing child dom animations with the [AnimationOptimizer]. This + * preventing child DOM animations with the [AnimationOptimizer]. This * prevents transitions on child elements while the parent is animating, * but will not stop running transitions once they have started. * @@ -88,9 +88,9 @@ * running animation check. * * `ng-animate-children` allows animation to be controlled on large chunks of - * dom. It only affects child elements, and allows the `always`, `never`, + * DOM. It only affects child elements, and allows the `always`, `never`, * and `auto` values to be specified. Always will always attempt animations - * on child dom directives, never will always prevent them (except in the + * on child DOM directives, never will always prevent them (except in the * case where a given element has `ng-animate="always"` specified), * and `auto` will defer the decision to the currently running animation * check. diff --git a/lib/bootstrap.dart b/lib/bootstrap.dart index fb28cb4ad..cf0be6ed4 100644 --- a/lib/bootstrap.dart +++ b/lib/bootstrap.dart @@ -23,86 +23,92 @@ class AngularModule extends Module { type(MetadataExtractor); value(Expando, _elementExpando); - value(NgApp, new NgApp(dom.window.document.documentElement)); } } -Injector _defaultInjectorFactory(List modules) => - new DynamicInjector(modules: modules); - /** - * This method is the main entry point to an angular application. + * Bootstraps AngularDart and defines which application module(s) are available to the app. * - * # The [ngBootstrap] is responsible for: + * NgApp is how you configure and run an Angular application. NgApp is abstract. There are two + * implementations: one is dynamic, using Mirrors; the other is static, using code generation. * - * 1. Locating the root element of the application, - * 2. Creating Angular [NgZone] - * 3. Inside the [NgZone] create an injector - * 4. Retrieve the [Compiler] and compile the root eleement + * To create an NgApp, import angular_dynamic.dart and call ngDynamicApp like so: + * + * import 'package:angular/angular.dart'; + * import 'package:angular/angular_dynamic.dart'; * + * class HelloWorldController { + * ... + * } * - * # Parameters: + * main() { + * ngDynamicApp() + * .addModule(new Module()..type(HelloWorldController)) + * .run(); + * } * - * - [module] Optional application module to add to the [Injector]. - * - [modules] Optional list of [Module]s to add to the [Injector] (when more - * than one is needed). - * - [element] Optional root element of the application. If non specified, the - * the root element is looked up using the [selector]. If the selector can - * not identify a root, the root [HTML] element is used. - * - [selector] Optional CSS selector used to locate the root element for the - * application. - * - [injectorFactory] Optional factory responsible for creating the injector. + * On `pub build`, ngDynamicApp becomes ngStaticApp, as pub generates the getters, + * setters, annotations, and factories for the root Injector that [ngApp] creates. This * * + * Here, the ngBootstrap method performs the following actions: + * + * 1. Locating the root element of the application, + * 2. Creating Angular [NgZone] + * 3. Inside the [NgZone] create an injector + * 4. Retrieve the [Compiler] and compile the root element * - * # A typical way to boostrap an Angular application: * - * var myAppModule = new Module(); - * myAppModule.type(MyType); - * .... - * Injector injector = ngBootstrap(module: myAppModule); */ -Injector ngBootstrap({ - Module module: null, - List modules: null, - dom.Element element: null, - String selector: '[ng-app]', - Injector injectorFactory(List modules): _defaultInjectorFactory}) { - _publishToJavaScript(); - var ngModules = [new AngularModule()]; - if (module != null) ngModules.add(module); - if (modules != null) ngModules.addAll(modules); - if (element == null) { - element = dom.querySelector(selector); - if (element == null) { - element = dom.window.document.childNodes - .firstWhere((e) => e is dom.Element); - } +abstract class NgApp { + static _find(String selector, [dom.Element defaultElement]) { + var element = dom.window.document.querySelector(selector); + if (element == null) element = defaultElement; + if (element == null)throw "Could not find application element '$selector'."; + return element; } - // The injector must be created inside the zone, so we create the - // zone manually and give it back to the injector as a value. - NgZone zone = new NgZone(); - ngModules.add(new Module() + final NgZone zone = new NgZone(); + final AngularModule ngModule = new AngularModule(); + final List modules = []; + dom.Element element; + + dom.Element selector(String selector) => element = _find(selector); + + NgApp(): element = _find('[ng-app]', dom.window.document.documentElement) { + modules.add(ngModule); + ngModule ..value(NgZone, zone) - ..value(NgApp, new NgApp(element)) - ..factory(dom.Node, (i) => i.get(NgApp).root)); + ..value(NgApp, this) + ..factory(dom.Node, (i) => i.get(NgApp).element); + } + + Injector injector; - return zone.run(() { - var rootElements = [element]; - Injector injector = injectorFactory(ngModules); - initializeDateFormatting(null, null).then((_) { - var compiler = injector.get(Compiler); - var blockFactory = compiler(rootElements, injector.get(DirectiveMap)); - blockFactory(injector, rootElements); + NgApp addModule(Module module) { + modules.add(module); + return this; + } + + Injector run() { + _publishToJavaScript(); + return zone.run(() { + var rootElements = [element]; + Injector injector = createInjector(); + ExceptionHandler exceptionHandler = injector.get(ExceptionHandler); + initializeDateFormatting(null, null).then((_) { + try { + var compiler = injector.get(Compiler); + var blockFactory = compiler(rootElements, injector.get(DirectiveMap)); + blockFactory(injector, rootElements); + } catch (e, s) { + exceptionHandler(e, s); + } + }); + return injector; }); - return injector; - }); -} + } -/// Holds a reference to the root of the application used by ngBootstrap. -class NgApp { - final dom.Element root; - NgApp(this.root); + Injector createInjector(); } diff --git a/lib/directive/module.dart b/lib/directive/module.dart index a925c22dc..799c9b4f0 100644 --- a/lib/directive/module.dart +++ b/lib/directive/module.dart @@ -1,3 +1,12 @@ +/** +* +* Directives available in the main [angular.dart](#angular/angular) library. +* +* This package is imported for you as part of [angular.dart](#angular/angular), +* and lists all of the basic directives that are part of Angular. +* +* +*/ library angular.directive; import 'package:di/di.dart'; diff --git a/lib/filter/module.dart b/lib/filter/module.dart index 5c90c5af4..e78780644 100644 --- a/lib/filter/module.dart +++ b/lib/filter/module.dart @@ -1,3 +1,12 @@ +/** +* +* Filters available in the main [angular.dart](#angular/angular) library. +* +* This package is imported for you as part of [angular.dart](#angular/angular), +* and lists all of the basic filters that are part of Angular. +* +* +*/ library angular.filter; import 'dart:convert' show JSON; diff --git a/lib/mock/module.dart b/lib/mock/module.dart index 8700e9120..083c34af4 100644 --- a/lib/mock/module.dart +++ b/lib/mock/module.dart @@ -1,3 +1,16 @@ +/** +* +* Classes and utilities for testing and prototyping in AngularDart. +* +* This is an optional library. You must import it in addition to the [angular.dart] +* (#angular/angular) library, +* like so: +* +* import 'package:angular/angular.dart'; +* import 'package:angular/mock/module.dart'; +* +* +*/ library angular.mock; import 'dart:async' as dart_async; diff --git a/lib/perf/module.dart b/lib/perf/module.dart index 3a84665a6..b997f8fa8 100644 --- a/lib/perf/module.dart +++ b/lib/perf/module.dart @@ -1,3 +1,16 @@ +/** +* +* Classes and utilities for analyzing performance in AngularDart. +* +* This is an optional library. You must import it in addition to the [angular.dart] +* (#angular/angular) library, +* like so: +* +* import 'package:angular/angular.dart'; +* import 'package:angular/perf/module.dart'; +* +* +*/ library angular.perf; import 'dart:html' as dom; diff --git a/scripts/generate-documentation.sh b/scripts/generate-documentation.sh index e7ea9337c..c7cb636a0 100755 --- a/scripts/generate-documentation.sh +++ b/scripts/generate-documentation.sh @@ -20,7 +20,6 @@ echo "Generating documentation" filter/module.dart \ directive/module.dart \ animate/module.dart \ - utils.dart \ mock/module.dart \ perf/module.dart \