docs(dev guide): structural-directives - ts minor edits, dart first versiondocs(dev guide): structural-directives - ts minor edits, dart first version (#1277)

Copyedits and other minor edits for TS
+ first version of the chapter for Dart

Author: chalin

public/_includes/_util-fns.jade

@@ -23,8 +23,10 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
 
 mixin makeTabs(filePaths, regions, tabNames, stylePatterns)
   - filePaths = strSplit(filePaths);
+  - if (adjustExamplePath) filePaths = filePaths.map(adjustExamplePath);
   - regions = strSplit(regions, filePaths.length);
   - tabNames = strSplit(tabNames, filePaths.length);
+  - if (adjustExampleTitle) tabNames = tabNames.map(adjustExampleTitle);
 
   code-tabs
       each filePath,index in filePaths

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

@@ -5,11 +5,13 @@ mixin liveExLinks(name)
     [Run the live example](https://angular-examples.github.io/#{name}) |
     [View its source code](https://github.com/angular-examples/#{name})
 
-- var adjustExamplePath = function(path) {
+- var adjustExamplePath = function(_path) {
+-   if(!_path) return _path;
+-   var path = _path.trim();
 -   var folder = getFolder(path);
 -   var extn = getExtn(path);
 -   // if(extn == 'dart') return path;
--   var baseName = getBaseFileName(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)$/);
 -   // Adjust the folder path, e.g., ts -> dart 
@@ -18,15 +20,19 @@ mixin liveExLinks(name)
 -   baseNameNoExt = baseNameNoExt.replace(/[\-\.]/g, '_');
 -   // Adjust the file extension
 -   if(extn == 'ts') extn = 'dart';
--   return folder + '/' + baseNameNoExt + '.' + extn;
+-   return (folder ? folder + '/' : '') + baseNameNoExt + (extn ? '.' + extn : '');
 - };
 
-- var adjustExampleTitle = function(title) {
--   // Assume title is a path if it ends with an extension like '.foo'.
--   if(title && title.match(/\.\w+$/) && adjustExamplePath) {
--     var isAbsolutePath = title.match(/^\//);
--     title = adjustExamplePath(title);
--     if(!isAbsolutePath && title.match(/^\//)) title = title.substring(1);
+- var adjustExampleTitle = function(_title) {
+-   if(!_title || !adjustExamplePath) return _title;
+-   var title = _title.trim();
+-   // Assume title is a path if it ends with an extension like '.foo',
+-   // optionally followed by '(excerpt)' with or without parentheses.
+-   var matches = title.match(/(.*\.\w+)($|\s*\(?excerpt\)?$)/);
+-   if(matches && matches.length == 3) {
+-     // e.g. matches == ['abc.ts (excerpt)', 'abc.ts', ' (excerpt)']
+-     var path = adjustExamplePath(matches[1]);
+-     title = path + matches[2];
 -   }
 -   return title;
 - }

public/docs/dart/latest/guide/structural-directives.jade

@@ -1,12 +1,12 @@
-include ../_util-fns
+extends ../../../ts/latest/guide/structural-directives.jade
 
-:marked
-  We're working on the Dart version of this chapter.
-  In the meantime, please see these resources:
+block includes
+  include ../_util-fns
 
-  * [Structural Directives](/docs/ts/latest/guide/structural-directives.html):
-    The TypeScript version of this chapter
+block liveExample
+  +liveExLinks('structural-directives')
 
-  * [Dart source code](https://github.com/angular/angular.io/tree/master/public/docs/_examples/structural-directives/dart):
-    A preliminary version of the example code that will appear in this chapter
-   
+block unless-intro
+  :marked
+    Creating a directive is similar to creating a component.
+    Here is how we begin:

public/docs/ts/latest/guide/structural-directives.jade

@@ -1,4 +1,5 @@
-include ../_util-fns
+block includes
+  include ../_util-fns
 
 :marked
   One of the defining features of a single page application is its manipulation
@@ -9,12 +10,14 @@ include ../_util-fns
 
   In this chapter we will
   - [learn what structural directives are](#definition)
-  - [study *ngIf*](#ng-if)
+  - [study *ngIf*](#ngIf)
   - [discover the <template> element](#template)
   - [understand the asterisk (\*) in **ngFor*](#asterisk)
   - [write our own structural directive](#unless)
 
-  [Live example](/resources/live-examples/structural-directives/ts/plnkr.html)
+block liveExample
+  :marked
+    [Live example](/resources/live-examples/structural-directives/ts/plnkr.html)
 
 <a id="definition"></a>
 .l-main-section
@@ -42,7 +45,7 @@ include ../_util-fns
 +makeExample('structural-directives/ts/app/structural-directives.component.html', 'structural-directives')(format=".")
 
 
-<a id="ng-if"></a>
+<a id="ngIf"></a>
 .l-main-section
 :marked
   ## NgIf Case Study
@@ -163,7 +166,7 @@ figure.image-display
   We can confirm these effects by wrapping the middle "hip" of the phrase "Hip! Hip! Hooray!" within a `<template>` tag.
 +makeExample('structural-directives/ts/app/structural-directives.component.html', 'template-tag')(format=".")
 :marked
-  The display is a 'Hip!' short of perfect enthusiasm. The DOM effects are different when Angular is control.
+  The display is a 'Hip! Hooray!', short of perfect enthusiasm. The DOM effects are different when Angular is in control.
 figure.image-display
   img(src='/resources/images/devguide/structural-directives/template-in-out-of-a2.png' alt="template outside angular")
 
@@ -225,18 +228,19 @@ figure.image-display
   Unlike `ngIf` which displays the template content when `true`,
   our directive displays the content when the condition is ***false***.
 
-:marked
-  Creating a directive is similar to creating a component.
-  * import the `Directive` decorator.
+block unless-intro
+  :marked
+    Creating a directive is similar to creating a component.
+    * import the `Directive` decorator.
 
-  * add a CSS **attribute selector** (in brackets) that identifies our directive.
+    * add a CSS **attribute selector** (in brackets) that identifies our directive.
 
-  * specify the name of the public `input` property for binding
-  (typically the name of the directive itself).
+    * specify the name of the public `input` property for binding
+    (typically the name of the directive itself).
 
-  * apply the decorator to our implementation class.
+    * apply the decorator to our implementation class.
 
-  Here is how we begin:
+    Here is how we begin:
 
 +makeExample('structural-directives/ts/app/unless.directive.ts', 'unless-declaration', 'unless.directive.ts (excerpt)')(format=".")
 .l-sub-section
@@ -264,11 +268,10 @@ figure.image-display
 +makeExample('structural-directives/ts/app/unless.directive.ts', 'unless-constructor')(format=".")
 
 :marked
-  The consumer of our directive will bind a `true` | `false` value to our directive's `myUnless` input property.
+  The consumer of our directive will bind a boolean value to our directive's `myUnless` input property.
   The directive adds or removes the template based on that value.
 
-  Let's add the `myUnless` property now as a setter-only
-  [definedProperty](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty).
+  Let's add the `myUnless` property now as a setter-only property.
 
 +makeExample('structural-directives/ts/app/unless.directive.ts', 'unless-set')(format=".")
 .l-sub-section
@@ -278,7 +281,7 @@ figure.image-display
   Nothing fancy here: if the condition is false,
   we render the template, otherwise we clear the element content.
 
-  The end result should look like below:
+  The end result should look like this:
 
 +makeExample('structural-directives/ts/app/unless.directive.ts', null, 'unless.directive.ts')
 
@@ -297,7 +300,7 @@ figure.image-display
   Our `myUnless` directive is dead simple. Surely we left something out.
   Surely `ngIf` is more complex?
 
-  [Look at the source code](https://github.com/angular/angular/blob/master/modules/angular2/src/common/directives/ng_if.ts).
+  [Look at the source code](https://github.com/angular/angular/blob/master/modules/%40angular/common/src/directives/ng_if.ts).
   It's well documented and we shouldn't be shy
   about consulting the source when we want to know how something works.