docs(quickstart-ts/dart): updated prose and example code; consolidate for TS&Dart

closes #1396

Author: chalin

public/_includes/_util-fns.jade

@@ -4,15 +4,25 @@
 //- Should be one of: 'ts', 'dart' or 'js'. Set in lang specific _util-fns file.
 - var _docsFor = ''; 
 
+//- Should match `_docsFor`, but in this case provides the full capitalized
+//- name of the language.
+- var _Lang = 'TypeScript';
+
 //- Simple "macros" used via interpolation in text:
 //- e.g., the #{_priv}el variable has an `@Input` #{_decorator}.
 
 //- Use #{_decorator} whereever the word "decorator" is expected, provided it is not
 //- preceded by the article "a". (E.g., will be "annotation" for Dart)
 - var _decorator = 'decorator';
 
+//- Articles (which toggle between 'a' and 'an'). Used for, e.g.,
+//- array vs. list; decorator vs. annotation.
+- var _a = 'a';
+- var _an = 'an';
+
 //- TS arrays vs. Dart lists
 - var _array = 'array';
+//- Deprecate now that we have the articles _a and _an
 - var _an_array = 'an array';
 
 //- Promise vs. Future, etc
@@ -48,6 +58,7 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
   - var frag = getFrag(filePath, region);
   - var defaultFormat = frag.split('\n').length > 2 ? "linenums" : "";
   - var format = attributes.format || defaultFormat;
+  - if (attributes.format === '.') format = '';
   - var avoid = !!attributes.avoid;
 
   if (title)
@@ -57,6 +68,13 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
       .example-title #{title}
   code-example(language="#{language}" format="#{format}")
     != styleString(frag, stylePatterns)
+    
+//- Like makeExample, but doesn't show line numbers and
+//- title is appened with `(excerpt)` if it doesn't already
+//- end with a parenthetical remark.
+mixin makeExcerpt(_filePath, region, _title, stylePatterns)
+  - if (_title && !_title.match(/\([\w ]+\)$/)) _title = _title + ' (excerpt)';
+  +makeExample(_filePath, region, _title, stylePatterns)(format='.')
 
 mixin makeTabs(filePaths, regions, tabNames, stylePatterns)
   - filePaths = strSplit(filePaths);

public/docs/_examples/quickstart/dart/lib/app_component.dart

@@ -0,0 +1,12 @@
+// #docregion
+// #docregion import
+import 'package:angular2/core.dart';
+// #enddocregion import
+
+// #docregion metadata
+@Component(
+    selector: 'my-app',
+    template: '<h1>My First Angular 2 App</h1>')
+// #enddocregion metadata
+// #docregion class
+class AppComponent {}

public/docs/_examples/quickstart/dart/web/main.dart

@@ -1,10 +1,8 @@
 // #docregion
-import 'package:angular2/core.dart';
 import 'package:angular2/platform/browser.dart';
 
-@Component(selector: 'my-app', template: '<h1>My First Angular 2 App</h1>')
-class AppComponent {}
+import 'package:angular2_getting_started/app_component.dart';
 
-main() {
+void main() {
   bootstrap(AppComponent);
 }

public/docs/_examples/quickstart/dart/web/styles_1.css

@@ -0,0 +1,14 @@
+/* #docregion */
+h1 {
+  color: #369;
+  font-family: Arial, Helvetica, sans-serif;
+  font-size: 250%;
+}
+body {
+  margin: 2em;
+}
+
+/*
+* See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css
+* for the full set of master styles used by the documentation samples
+*/

public/docs/_examples/quickstart/ts/app/app.component.ts

@@ -9,6 +9,6 @@ import { Component } from '@angular/core';
   template: '<h1>My First Angular 2 App</h1>'
 })
 // #enddocregion metadata
-// #docregion export
+// #docregion class
 export class AppComponent { }
-// #enddocregion export
+// #enddocregion class

public/docs/_examples/quickstart/ts/styles.1.css

@@ -1,25 +1,14 @@
 /* #docregion */
-/* Master Styles */
 h1 {
-  color: #369; 
-  font-family: Arial, Helvetica, sans-serif;   
+  color: #369;
+  font-family: Arial, Helvetica, sans-serif;
   font-size: 250%;
 }
-h2, h3 { 
-  color: #444;
-  font-family: Arial, Helvetica, sans-serif;   
-  font-weight: lighter;
-}
-body { 
-  margin: 2em; 
-}
-body, input[text], button { 
-  color: #888; 
-  font-family: Cambria, Georgia; 
+body {
+  margin: 2em;
 }
 
-/* 
- * See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css
- * for the full set of master styles used by the documentation samples
- */
- 
+ /*
+  * See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css
+  * for the full set of master styles used by the documentation samples
+  */

public/docs/_examples/quickstart/ts/systemjs.config.1.js

@@ -39,9 +39,6 @@
     packages: packages
   }
 
-  // filterSystemConfig - index.html's chance to modify config before we register it.
-  if (global.filterSystemConfig) { global.filterSystemConfig(config); }
-
   System.config(config);
 
 })(this);

public/docs/_examples/systemjs.config.js

@@ -1,7 +1,6 @@
 /**
  * System configuration for Angular 2 samples
  * Adjust as necessary for your application needs.
- * Override at the last minute with global.filterSystemConfig (as plunkers do)
  */
 (function(global) {
 
@@ -42,9 +41,6 @@
     packages: packages
   }
 
-  // filterSystemConfig - index.html's chance to modify config before we register it.
-  if (global.filterSystemConfig) { global.filterSystemConfig(config); }
-
   System.config(config);
 
 })(this);

public/docs/dart/latest/_util-fns.jade

@@ -4,18 +4,21 @@ include ../../../_includes/_util-fns
 - var _docsFor = 'dart';
 - var _decorator = 'annotation';
 - var _array = 'list';
-- var _an_array = 'a list';
+- var _an_array = 'a list'; //- Deprecate now that we have the articles
+- var _a = 'an';
+- var _an = 'a';
 - var _priv = '_';
+- var _Lang = 'Dart';
 - var _Promise = 'Future';
 - var _Observable = 'Stream';
 
 mixin liveExampleLink(linkText, exampleUrlPartName)
-  a(href='https://angular-examples.github.io/#{exampleUrlPartName}')= linkText
+  a(href='https://angular-examples.github.io/#{exampleUrlPartName}' target="_blank")= linkText
 
 mixin liveExampleLink2(linkText, exampleUrlPartName)
   - var liveExampleSourceLinkText = attributes.srcLinkText || 'view source'
   | #[+liveExampleLink(linkText, exampleUrlPartName)] 
-  | (#[a(href='https://github.com/angular-examples/#{exampleUrlPartName}') #{liveExampleSourceLinkText}])
+  | (#[a(href='https://github.com/angular-examples/#{exampleUrlPartName}' target="_blank") #{liveExampleSourceLinkText}])
 
 - var adjustExamplePath = function(_path) {
 -   if(!_path) return _path;
@@ -25,9 +28,11 @@ mixin liveExampleLink2(linkText, exampleUrlPartName)
 -   // if(extn == 'dart') return path;
 -   var baseName = getBaseFileName(path) || path; // TODO: have getBaseFileName() return path
 -   var baseNameNoExt = baseName.substr(0,baseName.length - (extn.length + 1));
--   var inWebFolder = baseNameNoExt.match(/^(main|index)$/);
+-   var inWebFolder = baseNameNoExt.match(/^(main|index(\.\d)?)$/);
 -   // Adjust the folder path, e.g., ts -> dart 
--   folder = folder.replace(/(^|\/)ts\//, '$1dart/').replace(/(^|\/)app($|\/)/, inWebFolder ? '$1web$2' : '$1lib$2');
+-   folder = folder.replace(/(^|\/)ts($|\/)/, '$1dart$2').replace(/(^|\/)app($|\/)/, inWebFolder ? '$1web$2' : '$1lib$2');
+-   // Special case not handled above: e.g., index.html -> web/index.html
+-   if(baseNameNoExt.match(/^(index|styles)(\.\d)?$/)) folder = (folder ? folder + '/' : '') + 'web';
 -   // In file name, replace special characters with underscore
 -   baseNameNoExt = baseNameNoExt.replace(/[\-\.]/g, '_');
 -   // Adjust the file extension
@@ -40,7 +45,7 @@ mixin liveExampleLink2(linkText, exampleUrlPartName)
 -   var title = _title.trim();
 -   // Assume title is a path if it ends with an extension like '.foo',
 -   // optionally followed by some comment in parentheses.
--   var matches = title.match(/(.*\.\w+)($|\s*\([\w ]+\)?$)/);
+-   var matches = title.match(/(.*\.\w+)($|\s*\([\w ]+\)$)/);
 -   if(matches && matches.length == 3) {
 -     // e.g. matches == ['abc.ts (excerpt)', 'abc.ts', ' (excerpt)']
 -     var path = adjustExamplePath(matches[1]);