From bf3ed182a719a6d428fe304ebcbef7b32132fe0c Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Fri, 4 Mar 2016 17:56:41 -0800 Subject: [PATCH] docs: left nav is driven by _data.json files --- public/docs/_includes/_side-nav.jade | 96 ++- public/docs/_layout.jade | 3 +- public/docs/dart/latest/_data.json | 30 +- public/docs/dart/latest/_nav.jade | 58 -- public/docs/dart/latest/cheatsheet.jade | 3 +- public/docs/dart/latest/cookbook/_data.json | 9 +- public/docs/dart/latest/glossary.jade | 14 + public/docs/dart/latest/guide/_data.json | 60 +- public/docs/dart/latest/guide/cheatsheet.jade | 7 +- public/docs/dart/latest/guide/glossary.jade | 15 +- public/docs/dart/latest/tutorial/_data.json | 17 +- public/docs/js/latest/_data.json | 30 +- public/docs/js/latest/_nav.jade | 61 -- public/docs/js/latest/cheatsheet.jade | 3 +- public/docs/js/latest/cookbook/_data.json | 6 +- public/docs/js/latest/glossary.jade | 14 + public/docs/js/latest/guide/_data.json | 55 +- public/docs/js/latest/guide/cheatsheet.jade | 7 +- public/docs/js/latest/guide/glossary.jade | 15 +- public/docs/js/latest/tutorial/_data.json | 17 +- public/docs/ts/latest/_data.json | 30 +- public/docs/ts/latest/_nav.jade | 63 -- public/docs/ts/latest/cheatsheet.jade | 3 +- public/docs/ts/latest/cookbook/_data.json | 6 +- public/docs/ts/latest/glossary.jade | 637 +++++++++++++++++ public/docs/ts/latest/guide/_data.json | 49 +- public/docs/ts/latest/guide/cheatsheet.jade | 7 +- public/docs/ts/latest/guide/glossary.jade | 638 +----------------- .../ts/latest/testing/first-app-tests.jade | 18 +- .../latest/testing/jasmine-testing-101.jade | 22 +- .../testing/testing-an-angular-pipe.jade | 20 +- public/docs/ts/latest/tutorial/_data.json | 15 +- 32 files changed, 1017 insertions(+), 1011 deletions(-) delete mode 100644 public/docs/dart/latest/_nav.jade create mode 100644 public/docs/dart/latest/glossary.jade delete mode 100644 public/docs/js/latest/_nav.jade create mode 100644 public/docs/js/latest/glossary.jade delete mode 100644 public/docs/ts/latest/_nav.jade create mode 100644 public/docs/ts/latest/glossary.jade diff --git a/public/docs/_includes/_side-nav.jade b/public/docs/_includes/_side-nav.jade index 216bdd6b6c..9ff37c0608 100644 --- a/public/docs/_includes/_side-nav.jade +++ b/public/docs/_includes/_side-nav.jade @@ -1,16 +1,89 @@ -- var lang = current.path[1] +// Include this file ONLY when current.path[2] is defined +- var tracks = function(src, selector) { +- var base = '/docs/' + current.path[1] + '/' + current.path[2] + '/'; +- var secondaryPath = public.docs[current.path[1]][current.path[2]] +- var data = src ? secondaryPath[src] && secondaryPath[src]._data : secondaryPath._data; +- if (!data) return []; + +- var track = []; +- var selector = selector || function() { return true; }; +- var prefix = base + (src ? src + '/' : ''); +- for (prop in data) { +- var item = data[prop]; +- item[0] = prop; +- if (prop[0] !== '_' && !item.hide && selector(item)) { +- var file = prop !== 'index' ? prop + '.html' : '' +- item.file = file; +- item.href = prefix + file; +- item.navTitle = item.navTitle || item.title; +- item.tooltip = item.description || item.intro || ''; +- track.push(item); +- } +- } +- return track; +- } + +- var tutorial = tracks('tutorial'); +- var cookbook = tracks('cookbook'); +- var basics = tracks('guide', function(item) { return item.basics; }); +- var guide = tracks('guide', function(item) { return !item.basics; }); +- var qs = tracks('', function(item) { return item[0] === 'quickstart'; })[0] || {}; +- var reference = tracks('', function(item) { return item.reference; }); +- var resources = tracks('', function(item) { return item.resources; }); nav.side-nav.l-pinned-left.l-layer-4.l-offset-nav - // SEARCH BAR header.side-nav-search.st-input-wrapper form.st-input-inner label(for="search-io" class="is-hidden") Search Docs input(type="search" id="search-io" placeholder="SEARCH DOCS...") button(class="mobile-trigger button" aria-label="View Docs Menu" ng-click="appCtrl.toggleDocsMenu($event)" md-button) Docs - + div(class="side-nav-secondary" ng-class="appCtrl.showDocsNav ? 'is-visible' : ''") - != partial("../" + lang + "/latest/_nav") + .nav-blocks + .nav-title Tutorial + .nav-primary-link + a(href="#{qs.href}" title="#{qs.tooltip}") #{qs.navTitle} + .nav-sub-title Case Study: Tour of Heroes + .nav-ordered-lists + ol + each item in tutorial + li: a(href="#{item.href}" title="#{item.tooltip}") #{item.navTitle} + + .nav-blocks + .nav-title Basics + .nav-ordered-lists + ol + each item in basics + li: a(href="#{item.href}" title="#{item.tooltip}") #{item.navTitle} + + .nav-blocks + .nav-title Developer Guide + .nav-unordered-lists + ul + each item in guide + li: a(href="#{item.href}" title="#{item.tooltip}") #{item.navTitle} + + .nav-blocks + .nav-title Cookbook + .nav-unordered-lists + ul + each item in cookbook + li: a(href="#{item.href}" title="#{item.tooltip}") #{item.navTitle} + + .nav-blocks + .nav-title Reference + .nav-unordered-lists + ul + each item in reference + li: a(href="#{item.href}" title="#{item.tooltip}") #{item.navTitle} + + .nav-blocks + .nav-title Resources + .nav-unordered-lists + ul + each item in resources + li: a(href="#{item.href}" title="#{item.tooltip}") #{item.navTitle} script. @@ -20,11 +93,9 @@ script. if (!leftNav) {return;} var links = leftNav.getElementsByTagName('a'); var path = location.toString(); - // remove trailing '/' - if (path[path.length-1] === '/') {path = path.slice(0, path.length-1);} - // remove trailing '/index.html' (11 chars) for matching purposes. - if (path.lastIndexOf('/index.html') === path.length-11) { - path = path.slice(0, -11); + // remove trailing 'index.html' (10 chars) for matching purposes. + if (path.lastIndexOf('index.html') === path.length-10) { + path = path.slice(0, -10); } for (var i=0; i < links.length; i++){ // assumes fresh page each time so no need to clear class @@ -33,10 +104,11 @@ script. parent.classList.add('is-selected'); if(parent.offsetTop > window.innerHeight && parent.scrollIntoView){ - parent.scrollIntoView(false); - // parent.scrollTop(); + sideNav = document.getElementsByClassName('side-nav')[0]; + sideNav.scrollTop = parent.offsetTop - (window.innerHeight/2); + //alert("offsetTop: " + parent.offsetTop + " side-nav top is " + sideNav.scrollTop); } break; } } - })() \ No newline at end of file + })() diff --git a/public/docs/_layout.jade b/public/docs/_layout.jade index 3ea45a9136..ba13f435a6 100644 --- a/public/docs/_layout.jade +++ b/public/docs/_layout.jade @@ -5,7 +5,8 @@ html(lang="en" ng-app="angularIOApp" itemscope itemtype="http://schema.org/Frame body(class="l-offset-nav l-offset-side-nav" ng-controller="AppCtrl as appCtrl") != partial("../_includes/_main-nav") - != partial("_includes/_side-nav") + if current.path[2] + != partial("_includes/_side-nav") != partial("../_includes/_hero") != partial("../_includes/_banner") diff --git a/public/docs/dart/latest/_data.json b/public/docs/dart/latest/_data.json index 3eb7861626..8dd7a5e313 100644 --- a/public/docs/dart/latest/_data.json +++ b/public/docs/dart/latest/_data.json @@ -8,7 +8,8 @@ "quickstart": { "icon": "query-builder", - "title": "5 Min Quickstart" + "title": "5 Min Quickstart", + "description": "Get up and running with Angular 2" }, "tutorial": { @@ -16,10 +17,10 @@ "title": "Tutorial", "banner": "Angular 2 is currently in Beta." }, - + "guide": { "icon": "list", - "title": "Developers Guide", + "title": "Developer Guides", "banner": "Angular 2 is currently in Beta." }, @@ -28,20 +29,35 @@ "title": "Cookbook", "banner": "How to solve common implementation challenges." }, - + "api": { "icon": "book", - "title": "API Proposal" + "title": "API Preview", + "reference": true + }, + + "cheatsheet": { + "title": "Angular Cheat Sheet", + "intro": "A quick quide to Angular syntax.", + "reference": true }, + "glossary": { + "title": "Glossary", + "intro": "Brief definitions of the most important words in the Angular 2 vocabulary", + "reference": true + }, + "resources": { "icon": "play-circle-fill", "title": "Angular Resources", - "banner": "Angular 2 is currently in Beta." + "banner": "Angular 2 is currently in Beta.", + "resources": true }, "help": { "icon": "chat", - "title": "Help & Support" + "title": "Help & Support", + "resources": true } } diff --git a/public/docs/dart/latest/_nav.jade b/public/docs/dart/latest/_nav.jade deleted file mode 100644 index 324f01eb3c..0000000000 --- a/public/docs/dart/latest/_nav.jade +++ /dev/null @@ -1,58 +0,0 @@ -- var base = '/docs/dart/latest/' - -.nav-blocks - .nav-title Tutorial - .nav-primary-link - a(href='#{base}quickstart.html') 5 Min Quickstart - .nav-sub-title Case Study: Tour of Heroes - .nav-ordered-lists - ol - li: a(href='#{base}tutorial') Introduction - li: a(href='#{base}tutorial/toh-pt1.html') The Hero Editor - li: a(href='#{base}tutorial/toh-pt2.html') Master/Detail - li: a(href='#{base}tutorial/toh-pt3.html') Multiple Components - li: a(href='#{base}tutorial/toh-pt4.html') Services - li: a(href='#{base}tutorial/toh-pt5.html') Routing - -.nav-blocks - .nav-title Basics - .nav-ordered-lists - ol - li: a(href='#{base}guide') Overview - li: a(href='#{base}guide/architecture.html') Architecture - li: a(href='#{base}guide/displaying-data.html') Displaying Data - li: a(href='#{base}guide/user-input.html') User Input - li: a(href='#{base}guide/forms.html') Forms - li: a(href='#{base}guide/dependency-injection.html') Dependency Injection - li: a(href='#{base}guide/template-syntax.html') Template Syntax - li: a(href='#{base}guide/cheatsheet.html') Angular Cheat Sheet -.nav-blocks - .nav-title Developer Guide - .nav-unordered-lists - ul - li: a(href='#{base}guide/attribute-directives.html') Attribute Directives - li: a(href='#{base}guide/hierarchical-dependency-injection.html') Hierarchical Injectors - li: a(href='#{base}guide/server-communication.html') Http Client - li: a(href='#{base}guide/lifecycle-hooks.html') Lifecycle Hooks - li: a(href='#{base}guide/pipes.html') Pipes - li: a(href='#{base}guide/router.html') Routing & Navigation - li: a(href='#{base}guide/structural-directives.html') Structural Directives -.nav-blocks - .nav-title Cookbook - .nav-unordered-lists - ul - li: a(href='#{base}cookbook') Overview - li: a(href='#{base}cookbook/component-communication.html') Component Interaction -.nav-blocks - .nav-title Reference - .nav-unordered-lists - ul - li: a(href='#{base}api') API Preview - li: a(href='#{base}cheatsheet.html') Angular Cheat Sheet - li: a(href='#{base}guide/glossary.html') Glossary -.nav-blocks - .nav-title Resources - .nav-unordered-lists - ul - li: a(href='#{base}resources.html') Angular Resources - li: a(href='#{base}help.html') Help & Support diff --git a/public/docs/dart/latest/cheatsheet.jade b/public/docs/dart/latest/cheatsheet.jade index 3abbeff0f9..4548cf52e0 100644 --- a/public/docs/dart/latest/cheatsheet.jade +++ b/public/docs/dart/latest/cheatsheet.jade @@ -1,6 +1,7 @@ +- var base = current.path[4] ? '.' : './guide'; .banner p.text-body This cheat sheet is provisional and may change. Angular 2 is currently in Beta. article(class="l-content-small grid-fluid docs-content") .cheatsheet - ngio-cheatsheet(src='./guide/cheatsheet.json') + ngio-cheatsheet(src= base + '/cheatsheet.json') diff --git a/public/docs/dart/latest/cookbook/_data.json b/public/docs/dart/latest/cookbook/_data.json index e92ccaf6da..71d17069b1 100644 --- a/public/docs/dart/latest/cookbook/_data.json +++ b/public/docs/dart/latest/cookbook/_data.json @@ -1,14 +1,15 @@ { - "_listtype": "alpha", - "index": { "title": "Cookbook", + "navTitle": "Overview", "description": "A collection of recipes for common Angular application scenarios" }, "a1-a2-quick-reference": { - "title": "Angular 1 to 2 Quick Ref", - "description": "Learn how Angular 1 concepts and techniques map to Angular 2" + "title": "Angular 1 to 2 Quick Reference", + "navTitle": "Angular 1 to 2 Quick Ref", + "description": "Learn how Angular 1 concepts and techniques map to Angular 2", + "hide": true }, "component-communication": { diff --git a/public/docs/dart/latest/glossary.jade b/public/docs/dart/latest/glossary.jade new file mode 100644 index 0000000000..652c5d9a1a --- /dev/null +++ b/public/docs/dart/latest/glossary.jade @@ -0,0 +1,14 @@ +include _util-fns ++includeShared('{ts}', 'intro') ++includeShared('{ts}', 'a2') ++includeShared('{ts}', 'b-c') ++includeShared('{ts}', 'd1') ++includeShared('{ts}', 'd2') ++includeShared('{ts}', 'e1') ++includeShared('{ts}', 'e2') ++includeShared('{ts}', 'f-l') ++includeShared('{ts}', 'm1') ++includeShared('{ts}', 'n-s') ++includeShared('{ts}', 't1') + ++includeShared('{ts}', 'u-z') \ No newline at end of file diff --git a/public/docs/dart/latest/guide/_data.json b/public/docs/dart/latest/guide/_data.json index 78fb1d635b..ad902928f1 100644 --- a/public/docs/dart/latest/guide/_data.json +++ b/public/docs/dart/latest/guide/_data.json @@ -1,54 +1,70 @@ { - "_listtype": "ordered", - "index": { "title": "Documentation Overview", - "nextable":true + "navTitle": "Overview", + "description": "How to read and use this documentation", + "nextable": true, + "basics": true }, "architecture": { "title": "Architecture Overview", + "navTitle": "Architecture", "intro": "The basic building blocks of Angular 2 applications", - "nextable":true + "nextable": true, + "basics": true }, "displaying-data": { "title": "Displaying Data", "intro": "Interpolation and other forms of property binding help us show app data in the UI.", - "nextable":true + "nextable": true, + "basics": true }, "user-input": { "title": "User Input", "intro": "User input triggers DOM events. We listen to those events with event bindings that funnel updated values back into our components and models.", - "nextable":true + "nextable": true, + "basics": true }, "forms": { "title": "Forms", "intro": "A form creates a cohesive, effective, and compelling data entry experience. An Angular form coordinates a set of data-bound user controls, tracks changes, validates input, and presents errors.", - "nextable":true + "nextable": true, + "basics": true }, "dependency-injection": { "title": "Dependency Injection", "intro": "Angular's dependency injection system creates and delivers dependent services \"just-in-time\".", - "nextable":true + "nextable": true, + "basics": true }, "template-syntax": { "title": "Template Syntax", "intro": "Learn how to write templates that display data and consume user events with the help of data binding.", - "nextable":true + "nextable": true, + "basics": true }, + "cheatsheet": { + "title": "Angular Cheat Sheet", + "intro": "A quick quide to Angular syntax.", + "nextable": true, + "basics": true + }, + "attribute-directives": { "title": "Attribute Directives", "intro": "Attribute directives attach behavior to elements." }, "hierarchical-dependency-injection": { - "title": "Hierarchical Injectors", + "title": "Hierarchical Dependency Injectors", + "navTitle": "Hierarchical Injectors", "intro": "Angular's hierarchical dependency injection system supports nested injectors in parallel with the component tree." }, @@ -62,6 +78,12 @@ "intro": "Angular calls lifecycle hook methods on directives and components as it creates, changes, and destroys them." }, + "npm-packages": { + "title": "Npm Packages", + "intro": "Details of the recommended npm packages and the different kinds of package dependencies", + "hide": true + }, + "pipes": { "title": "Pipes", "intro": "Pipes transform displayed values within a template." @@ -77,13 +99,27 @@ "intro": "Angular has a powerful template engine that lets us easily manipulate the DOM structure of our elements." }, + "testing": { + "title": "Testing", + "intro": "Techniques and practices for testing an Angular 2 app", + "hide": true + }, + + "typescript-configuration": { + "title": "TypeScript Configuration", + "intro": "TypeScript configuration for Angular 2 developers", + "hide": true + }, + "upgrade": { "title": "Upgrading from 1.x", - "intro": "Angular 1 applications can be incrementally upgraded to Angular 2." + "intro": "Angular 1 applications can be incrementally upgraded to Angular 2.", + "hide": true }, "glossary": { "title": "Glossary", - "intro": "Brief definitions of the most important words in the Angular 2 vocabulary" + "intro": "Brief definitions of the most important words in the Angular 2 vocabulary", + "hide": true } } diff --git a/public/docs/dart/latest/guide/cheatsheet.jade b/public/docs/dart/latest/guide/cheatsheet.jade index fbc72411e3..ff8cc6085c 100644 --- a/public/docs/dart/latest/guide/cheatsheet.jade +++ b/public/docs/dart/latest/guide/cheatsheet.jade @@ -1,6 +1 @@ -.banner - p.text-body This cheat sheet is provisional and may change. Angular 2 is currently in Beta. - -article(class="l-content-small grid-fluid docs-content") - .cheatsheet - ngio-cheatsheet(src='./cheatsheet.json') +!= partial("../cheatsheet") diff --git a/public/docs/dart/latest/guide/glossary.jade b/public/docs/dart/latest/guide/glossary.jade index e70509c833..a66284569e 100644 --- a/public/docs/dart/latest/guide/glossary.jade +++ b/public/docs/dart/latest/guide/glossary.jade @@ -1,14 +1 @@ -include ../_util-fns -+includeShared('{ts}', 'intro') -+includeShared('{ts}', 'a2') -+includeShared('{ts}', 'b-c') -+includeShared('{ts}', 'd1') -+includeShared('{ts}', 'd2') -+includeShared('{ts}', 'e1') -+includeShared('{ts}', 'e2') -+includeShared('{ts}', 'f-l') -+includeShared('{ts}', 'm1') -+includeShared('{ts}', 'n-s') -+includeShared('{ts}', 't1') - -+includeShared('{ts}', 'u-z') \ No newline at end of file +!= partial("../glossary") diff --git a/public/docs/dart/latest/tutorial/_data.json b/public/docs/dart/latest/tutorial/_data.json index 9dc557a611..bf52bf1c4e 100644 --- a/public/docs/dart/latest/tutorial/_data.json +++ b/public/docs/dart/latest/tutorial/_data.json @@ -1,34 +1,33 @@ { - "_listtype": "ordered", - "index": { "title": "Tutorial: Tour of Heroes", + "navTitle": "Introduction", "intro": "The Tour of Heroes tutorial takes us through the steps of creating an Angular application in TypeScript.", - "nextable":true + "nextable": true }, "toh-pt1": { "title": "The Hero Editor", "intro": "We build a simple hero editor", - "nextable":true + "nextable": true }, "toh-pt2": { "title": "Master/Detail", "intro": "We build a master/detail page with a list of heroes", - "nextable":true + "nextable": true }, "toh-pt3": { "title": "Multiple Components", "intro": "We refactor the master/detail view into separate components", - "nextable":true + "nextable": true }, "toh-pt4": { "title": "Services", "intro": "We create a reusable service to manage our hero data calls", - "nextable":true + "nextable": true }, "toh-pt5": { "title": "Routing", "intro": "We add the Angular Component Router and learn to navigate among the views", - "nextable":true + "nextable": true } -} \ No newline at end of file +} diff --git a/public/docs/js/latest/_data.json b/public/docs/js/latest/_data.json index 97d3410172..8dd7a5e313 100644 --- a/public/docs/js/latest/_data.json +++ b/public/docs/js/latest/_data.json @@ -8,7 +8,8 @@ "quickstart": { "icon": "query-builder", - "title": "5 Min Quickstart" + "title": "5 Min Quickstart", + "description": "Get up and running with Angular 2" }, "tutorial": { @@ -16,10 +17,10 @@ "title": "Tutorial", "banner": "Angular 2 is currently in Beta." }, - + "guide": { "icon": "list", - "title": "Developer Guide", + "title": "Developer Guides", "banner": "Angular 2 is currently in Beta." }, @@ -28,20 +29,35 @@ "title": "Cookbook", "banner": "How to solve common implementation challenges." }, - + "api": { "icon": "book", - "title": "API Preview" + "title": "API Preview", + "reference": true + }, + + "cheatsheet": { + "title": "Angular Cheat Sheet", + "intro": "A quick quide to Angular syntax.", + "reference": true }, + "glossary": { + "title": "Glossary", + "intro": "Brief definitions of the most important words in the Angular 2 vocabulary", + "reference": true + }, + "resources": { "icon": "play-circle-fill", "title": "Angular Resources", - "banner": "Angular 2 is currently in Beta." + "banner": "Angular 2 is currently in Beta.", + "resources": true }, "help": { "icon": "chat", - "title": "Help & Support" + "title": "Help & Support", + "resources": true } } diff --git a/public/docs/js/latest/_nav.jade b/public/docs/js/latest/_nav.jade deleted file mode 100644 index 25a09f9b3d..0000000000 --- a/public/docs/js/latest/_nav.jade +++ /dev/null @@ -1,61 +0,0 @@ -- var base = '/docs/js/latest/' - -.nav-blocks - .nav-title Tutorial - .nav-primary-link - a(href='#{base}quickstart.html') 5 Min Quickstart - .nav-sub-title Case Study: Tour of Heroes - .nav-ordered-lists - ol - li: a(href='#{base}tutorial') Introduction - li: a(href='#{base}tutorial/toh-pt1.html') The Hero Editor - li: a(href='#{base}tutorial/toh-pt2.html') Master/Detail - li: a(href='#{base}tutorial/toh-pt3.html') Multiple Components - li: a(href='#{base}tutorial/toh-pt4.html') Services - li: a(href='#{base}tutorial/toh-pt5.html') Routing - -.nav-blocks - .nav-title Basics - .nav-ordered-lists - ol - li: a(href='#{base}guide') Overview - li: a(href='#{base}guide/architecture.html') Architecture - li: a(href='#{base}guide/displaying-data.html') Displaying Data - li: a(href='#{base}guide/user-input.html') User Input - li: a(href='#{base}guide/forms.html') Forms - li: a(href='#{base}guide/dependency-injection.html') Dependency Injection - li: a(href='#{base}guide/template-syntax.html') Template Syntax - li: a(href='#{base}guide/cheatsheet.html') Angular Cheat Sheet -.nav-blocks - .nav-title Developer Guide - .nav-unordered-lists - ul - li: a(href='#{base}guide/attribute-directives.html') Attribute Directives - li: a(href='#{base}guide/hierarchical-dependency-injection.html') Hierarchical Injectors - li: a(href='#{base}guide/server-communication.html') Http Client - li: a(href='#{base}guide/lifecycle-hooks.html') Lifecycle Hooks - li: a(href='#{base}guide/npm-packages.html') npm packages - li: a(href='#{base}guide/pipes.html') Pipes - li: a(href='#{base}guide/router.html') Routing & Navigation - li: a(href='#{base}guide/structural-directives.html') Structural Directives - li: a(href='#{base}guide/upgrade.html') Upgrading from 1.x -.nav-blocks - .nav-title Cookbook - .nav-unordered-lists - ul - li: a(href='#{base}cookbook') Overview - li: a(href='#{base}cookbook/a1-a2-quick-reference.html') Angular 1 to 2 Quick Ref - li: a(href='#{base}cookbook/component-communication.html') Component Interaction -.nav-blocks - .nav-title Reference - .nav-unordered-lists - ul - li: a(href='#{base}api') API Preview - li: a(href='#{base}cheatsheet.html') Angular Cheat Sheet - li: a(href='#{base}guide/glossary.html') Glossary -.nav-blocks - .nav-title Resources - .nav-unordered-lists - ul - li: a(href='#{base}resources.html') Angular Resources - li: a(href='#{base}help.html') Help & Support diff --git a/public/docs/js/latest/cheatsheet.jade b/public/docs/js/latest/cheatsheet.jade index 3abbeff0f9..4548cf52e0 100644 --- a/public/docs/js/latest/cheatsheet.jade +++ b/public/docs/js/latest/cheatsheet.jade @@ -1,6 +1,7 @@ +- var base = current.path[4] ? '.' : './guide'; .banner p.text-body This cheat sheet is provisional and may change. Angular 2 is currently in Beta. article(class="l-content-small grid-fluid docs-content") .cheatsheet - ngio-cheatsheet(src='./guide/cheatsheet.json') + ngio-cheatsheet(src= base + '/cheatsheet.json') diff --git a/public/docs/js/latest/cookbook/_data.json b/public/docs/js/latest/cookbook/_data.json index e92ccaf6da..f4bc414f46 100644 --- a/public/docs/js/latest/cookbook/_data.json +++ b/public/docs/js/latest/cookbook/_data.json @@ -1,13 +1,13 @@ { - "_listtype": "alpha", - "index": { "title": "Cookbook", + "navTitle": "Overview", "description": "A collection of recipes for common Angular application scenarios" }, "a1-a2-quick-reference": { - "title": "Angular 1 to 2 Quick Ref", + "title": "Angular 1 to 2 Quick Reference", + "navTitle": "Angular 1 to 2 Quick Ref", "description": "Learn how Angular 1 concepts and techniques map to Angular 2" }, diff --git a/public/docs/js/latest/glossary.jade b/public/docs/js/latest/glossary.jade new file mode 100644 index 0000000000..e6be332f6c --- /dev/null +++ b/public/docs/js/latest/glossary.jade @@ -0,0 +1,14 @@ +include _util-fns ++includeShared('{ts}', 'intro') ++includeShared('{ts}', 'a2') ++includeShared('{ts}', 'b-c') ++includeShared('{ts}', 'd1') ++includeShared('{ts}', 'd2') ++includeShared('{ts}', 'e1') ++includeShared('{ts}', 'e2') ++includeShared('{ts}', 'f-l') ++includeShared('{ts}', 'm1') ++includeShared('{ts}', 'n-s') ++includeShared('{ts}', 't1') ++includeShared('{ts}', 't2') ++includeShared('{ts}', 'u-z') \ No newline at end of file diff --git a/public/docs/js/latest/guide/_data.json b/public/docs/js/latest/guide/_data.json index ce7f54df6a..4d51476e66 100644 --- a/public/docs/js/latest/guide/_data.json +++ b/public/docs/js/latest/guide/_data.json @@ -1,53 +1,70 @@ { - "_listtype": "ordered", - "index": { "title": "Documentation Overview", - "nextable":true + "navTitle": "Overview", + "description": "How to read and use this documentation", + "nextable": true, + "basics": true }, "architecture": { "title": "Architecture Overview", + "navTitle": "Architecture", "intro": "The basic building blocks of Angular 2 applications", - "nextable":true + "nextable": true, + "basics": true }, "displaying-data": { "title": "Displaying Data", "intro": "Interpolation and other forms of property binding help us show app data in the UI.", - "nextable":true + "nextable": true, + "basics": true }, "user-input": { "title": "User Input", "intro": "User input triggers DOM events. We listen to those events with event bindings that funnel updated values back into our components and models.", - "nextable":true + "nextable": true, + "basics": true }, "forms": { "title": "Forms", - "intro": "A form creates a cohesive, effective, and compelling data entry experience. An Angular form coordinates a set of data-bound user controls, tracks changes, validates input, and presents errors." + "intro": "A form creates a cohesive, effective, and compelling data entry experience. An Angular form coordinates a set of data-bound user controls, tracks changes, validates input, and presents errors.", + "nextable": true, + "basics": true }, "dependency-injection": { "title": "Dependency Injection", "intro": "Angular's dependency injection system creates and delivers dependent services \"just-in-time\".", - "nextable":true + "nextable": true, + "basics": true }, "template-syntax": { "title": "Template Syntax", "intro": "Learn how to write templates that display data and consume user events with the help of data binding.", - "nextable":true + "nextable": true, + "basics": true }, + "cheatsheet": { + "title": "Angular Cheat Sheet", + "intro": "A quick quide to Angular syntax.", + "nextable": true, + "basics": true + }, + "attribute-directives": { "title": "Attribute Directives", "intro": "Attribute directives attach behavior to elements." }, "hierarchical-dependency-injection": { - "title": "Hierarchical Injectors", + "title": "Hierarchical Dependency Injectors", + "navTitle": "Hierarchical Injectors", "intro": "Angular's hierarchical dependency injection system supports nested injectors in parallel with the component tree." }, @@ -62,7 +79,7 @@ }, "npm-packages": { - "title": "npm packages", + "title": "Npm Packages", "intro": "Details of the recommended npm packages and the different kinds of package dependencies" }, @@ -81,13 +98,27 @@ "intro": "Angular has a powerful template engine that lets us easily manipulate the DOM structure of our elements." }, + "testing": { + "title": "Testing", + "intro": "Techniques and practices for testing an Angular 2 app", + "hide": true + }, + + "typescript-configuration": { + "title": "TypeScript Configuration", + "intro": "TypeScript configuration for Angular 2 developers", + "hide": true + }, + "upgrade": { "title": "Upgrading from 1.x", "intro": "Angular 1 applications can be incrementally upgraded to Angular 2." }, + "glossary": { "title": "Glossary", - "intro": "Brief definitions of the most important words in the Angular 2 vocabulary" + "intro": "Brief definitions of the most important words in the Angular 2 vocabulary", + "hide": true } } diff --git a/public/docs/js/latest/guide/cheatsheet.jade b/public/docs/js/latest/guide/cheatsheet.jade index fbc72411e3..ff8cc6085c 100644 --- a/public/docs/js/latest/guide/cheatsheet.jade +++ b/public/docs/js/latest/guide/cheatsheet.jade @@ -1,6 +1 @@ -.banner - p.text-body This cheat sheet is provisional and may change. Angular 2 is currently in Beta. - -article(class="l-content-small grid-fluid docs-content") - .cheatsheet - ngio-cheatsheet(src='./cheatsheet.json') +!= partial("../cheatsheet") diff --git a/public/docs/js/latest/guide/glossary.jade b/public/docs/js/latest/guide/glossary.jade index 761e6c1f93..a66284569e 100644 --- a/public/docs/js/latest/guide/glossary.jade +++ b/public/docs/js/latest/guide/glossary.jade @@ -1,14 +1 @@ -include ../_util-fns -+includeShared('{ts}', 'intro') -+includeShared('{ts}', 'a2') -+includeShared('{ts}', 'b-c') -+includeShared('{ts}', 'd1') -+includeShared('{ts}', 'd2') -+includeShared('{ts}', 'e1') -+includeShared('{ts}', 'e2') -+includeShared('{ts}', 'f-l') -+includeShared('{ts}', 'm1') -+includeShared('{ts}', 'n-s') -+includeShared('{ts}', 't1') -+includeShared('{ts}', 't2') -+includeShared('{ts}', 'u-z') \ No newline at end of file +!= partial("../glossary") diff --git a/public/docs/js/latest/tutorial/_data.json b/public/docs/js/latest/tutorial/_data.json index 9dc557a611..bf52bf1c4e 100644 --- a/public/docs/js/latest/tutorial/_data.json +++ b/public/docs/js/latest/tutorial/_data.json @@ -1,34 +1,33 @@ { - "_listtype": "ordered", - "index": { "title": "Tutorial: Tour of Heroes", + "navTitle": "Introduction", "intro": "The Tour of Heroes tutorial takes us through the steps of creating an Angular application in TypeScript.", - "nextable":true + "nextable": true }, "toh-pt1": { "title": "The Hero Editor", "intro": "We build a simple hero editor", - "nextable":true + "nextable": true }, "toh-pt2": { "title": "Master/Detail", "intro": "We build a master/detail page with a list of heroes", - "nextable":true + "nextable": true }, "toh-pt3": { "title": "Multiple Components", "intro": "We refactor the master/detail view into separate components", - "nextable":true + "nextable": true }, "toh-pt4": { "title": "Services", "intro": "We create a reusable service to manage our hero data calls", - "nextable":true + "nextable": true }, "toh-pt5": { "title": "Routing", "intro": "We add the Angular Component Router and learn to navigate among the views", - "nextable":true + "nextable": true } -} \ No newline at end of file +} diff --git a/public/docs/ts/latest/_data.json b/public/docs/ts/latest/_data.json index 1ce1112eb2..8dd7a5e313 100644 --- a/public/docs/ts/latest/_data.json +++ b/public/docs/ts/latest/_data.json @@ -8,7 +8,8 @@ "quickstart": { "icon": "query-builder", - "title": "5 Min Quickstart" + "title": "5 Min Quickstart", + "description": "Get up and running with Angular 2" }, "tutorial": { @@ -29,25 +30,34 @@ "banner": "How to solve common implementation challenges." }, - "testing": { - "icon": "list", - "title": "Testing Guides", - "banner": "Angular 2 is currently in Beta." - }, - "api": { "icon": "book", - "title": "API Preview" + "title": "API Preview", + "reference": true + }, + + "cheatsheet": { + "title": "Angular Cheat Sheet", + "intro": "A quick quide to Angular syntax.", + "reference": true }, + "glossary": { + "title": "Glossary", + "intro": "Brief definitions of the most important words in the Angular 2 vocabulary", + "reference": true + }, + "resources": { "icon": "play-circle-fill", "title": "Angular Resources", - "banner": "Angular 2 is currently in Beta." + "banner": "Angular 2 is currently in Beta.", + "resources": true }, "help": { "icon": "chat", - "title": "Help & Support" + "title": "Help & Support", + "resources": true } } diff --git a/public/docs/ts/latest/_nav.jade b/public/docs/ts/latest/_nav.jade deleted file mode 100644 index 90b8f661be..0000000000 --- a/public/docs/ts/latest/_nav.jade +++ /dev/null @@ -1,63 +0,0 @@ -- var base = '/docs/ts/latest/' - -.nav-blocks - .nav-title Tutorial - .nav-primary-link - a(href='#{base}quickstart.html') 5 Min Quickstart - .nav-sub-title Case Study: Tour of Heroes - .nav-ordered-lists - ol - li: a(href='#{base}tutorial') Introduction - li: a(href='#{base}tutorial/toh-pt1.html') The Hero Editor - li: a(href='#{base}tutorial/toh-pt2.html') Master/Detail - li: a(href='#{base}tutorial/toh-pt3.html') Multiple Components - li: a(href='#{base}tutorial/toh-pt4.html') Services - li: a(href='#{base}tutorial/toh-pt5.html') Routing - -.nav-blocks - .nav-title Basics - .nav-ordered-lists - ol - li: a(href='#{base}guide') Overview - li: a(href='#{base}guide/architecture.html') Architecture - li: a(href='#{base}guide/displaying-data.html') Displaying Data - li: a(href='#{base}guide/user-input.html') User Input - li: a(href='#{base}guide/forms.html') Forms - li: a(href='#{base}guide/dependency-injection.html') Dependency Injection - li: a(href='#{base}guide/template-syntax.html') Template Syntax - li: a(href='#{base}guide/cheatsheet.html') Angular Cheat Sheet -.nav-blocks - .nav-title Developer Guide - .nav-unordered-lists - ul - li: a(href='#{base}guide/attribute-directives.html') Attribute Directives - li: a(href='#{base}guide/hierarchical-dependency-injection.html') Hierarchical Injectors - li: a(href='#{base}guide/server-communication.html') Http Client - li: a(href='#{base}guide/lifecycle-hooks.html') Lifecycle Hooks - li: a(href='#{base}guide/npm-packages.html') Npm Packages - li: a(href='#{base}guide/pipes.html') Pipes - li: a(href='#{base}guide/router.html') Routing & Navigation - li: a(href='#{base}guide/structural-directives.html') Structural Directives - li: a(href='#{base}guide/testing.html') Testing - li: a(href='#{base}guide/typescript-configuration.html') TypeScript Configuration - li: a(href='#{base}guide/upgrade.html') Upgrading from 1.x -.nav-blocks - .nav-title Cookbook - .nav-unordered-lists - ul - li: a(href='#{base}cookbook') Overview - li: a(href='#{base}cookbook/a1-a2-quick-reference.html') Angular 1 to 2 Quick Ref - li: a(href='#{base}cookbook/component-communication.html') Component Interaction -.nav-blocks - .nav-title Reference - .nav-unordered-lists - ul - li: a(href='#{base}api') API Preview - li: a(href='#{base}cheatsheet.html') Angular Cheat Sheet - li: a(href='#{base}guide/glossary.html') Glossary -.nav-blocks - .nav-title Resources - .nav-unordered-lists - ul - li: a(href='#{base}resources.html') Angular Resources - li: a(href='#{base}help.html') Help & Support diff --git a/public/docs/ts/latest/cheatsheet.jade b/public/docs/ts/latest/cheatsheet.jade index 3abbeff0f9..4548cf52e0 100644 --- a/public/docs/ts/latest/cheatsheet.jade +++ b/public/docs/ts/latest/cheatsheet.jade @@ -1,6 +1,7 @@ +- var base = current.path[4] ? '.' : './guide'; .banner p.text-body This cheat sheet is provisional and may change. Angular 2 is currently in Beta. article(class="l-content-small grid-fluid docs-content") .cheatsheet - ngio-cheatsheet(src='./guide/cheatsheet.json') + ngio-cheatsheet(src= base + '/cheatsheet.json') diff --git a/public/docs/ts/latest/cookbook/_data.json b/public/docs/ts/latest/cookbook/_data.json index baf52bc46c..5dfbf9c992 100644 --- a/public/docs/ts/latest/cookbook/_data.json +++ b/public/docs/ts/latest/cookbook/_data.json @@ -1,13 +1,13 @@ { - "_listtype": "alpha", - "index": { "title": "Cookbook", + "navTitle": "Overview", "description": "A collection of recipes for common Angular application scenarios" }, "a1-a2-quick-reference": { - "title": "Angular 1 to 2 Quick Ref", + "title": "Angular 1 to 2 Quick Reference", + "navTitle": "Angular 1 to 2 Quick Ref", "description": "Learn how Angular 1 concepts and techniques map to Angular 2" }, diff --git a/public/docs/ts/latest/glossary.jade b/public/docs/ts/latest/glossary.jade new file mode 100644 index 0000000000..6498392b59 --- /dev/null +++ b/public/docs/ts/latest/glossary.jade @@ -0,0 +1,637 @@ +include _util-fns + +// #docregion intro +:marked + # Angular 2 Glossary + + Angular 2 has a vocabulary of its own. + Most Angular 2 terms are everyday English words + with a specific meaning within the Angular system. + + We have gathered here the most prominent terms + and a few less familiar ones that have unusual or + unexpected definitions. + + [A](#A) [B](#B) [C](#C) [D](#D) [E](#E) [F](#F) [G](#G) [H](#H) [I](#I) + [J](#J) [K](#K) [L](#L) [M](#M) [N](#N) [O](#O) [P](#P) [Q](#Q) [R](#R) + [S](#S) [T](#T) [U](#U) [V](#V) [W](#W) [X](#X) [Y](#Y) [Z](#Z) +// #enddocregion intro + +// #docregion a1 + +// #enddocregion a1 +.l-main-section +:marked + ## Annotation +.l-sub-section + :marked + In practice a synonym for [Decoration](#decorator). +// #enddocregion a-1 +// #docregion a-2 +:marked + ## Attribute Directive +.l-sub-section + :marked + A category of [Directive](#directive) that can listen to and modify the behavior of + other HTML elements, attributes, properties, and components. They are usually represented + as HTML attributes, hence the name. + + The `ngClass` directive for adding and removing CSS class names is a good example of + an Attribute Directive. +// #enddocregion a-2 + +// #docregion b-c +- var lang = current.path[1] +- var decorator = lang = 'dart' ? 'annotation' : '[decorator](#decorator)' +- var atSym = lang == 'js' ? '' : '@' + +.l-main-section +:marked + ## Barrel +.l-sub-section + :marked + A **barrel** is an Angular library module consisting of a logical grouping of single-purpose modules + such as `Component` and `Directive`. + + Familiar barrels include `angular2/core`, `angular2/common`, `angular2/platform/browser`, + `angular2/http`, and `angular2/router`. + + Barrels are packaged and shipped as [**bundles**](#bundle) that + we may load with script tags in our `index.html`. + + The script, `angular2.dev.js`, is a bundle. + + Learn more in "[Modules, barrels and bundles](https://github.com/angular/angular/blob/master/modules/angular2/docs/bundles/overview.md)". + +:marked + ## Binding +.l-sub-section + :marked + Almost always refers to [Data Binding](#data-binding) and the act of + binding an HTML object property to a data object property. + + May refer to a [Dependency Injection](#dependency-injection) binding + between a "token" or "key" and a dependency [provider](#provider). + This more rare usage should be clear in context. + +:marked + ## Bootstrap +.l-sub-section + :marked + We launch an Angular application by "bootstrapping" it with the `bootstrap` method. + The `bootstrap` method identifies an application's top level "root" [Component](#component) + and optionally registers service [providers](#provider) with the + [dependency injection system](#dependency-injection). + + One can bootstrap multiple apps in the same `index.html`, each with its own top level root. + +:marked + ## Bundle +.l-sub-section + :marked + Angular JavaScript libraries are shipped in **bundles** within an **npm package** + such as [angular2](https://www.npmjs.com/package/angular2). + + The scripts `angular2.dev.js`, `http.js`, `router.js`, and `Rx.js` are + familiar examples of bundles. + + A bundle contains one more more [**barrels**](#barrel) + and each barrel contains a collection of logically related [modules](#module) + + Familiar barrels include `angular2/core`, `angular2/common`, `angular2/platform/browser`, + `angular2/http`, `angular2/router`. + + Learn more in "[Modules, barrels and bundles](https://github.com/angular/angular/blob/master/modules/angular2/docs/bundles/overview.md)". + + +.l-main-section +:marked + ## Component +.l-sub-section + :marked + An Angular class responsible for exposing data + to a [View](#view) and handling most of the view’s display + and user-interaction logic. + + The Component is one of the most important building blocks in the Angular system. + It is, in fact, an Angular [Directive](#directive) with a companion [Template](#template). + + The developer applies the `#{atSym}Component` #{decorator} to + the component class, thereby attaching to the class the essential component metadata + that Angular needs to create a component instance and render it with its template + as a view. + + Those familiar with "MVC" and "MVVM" patterns will recognize + the Component in the role of "Controller" or "View Model". +// #enddocregion b-c + +// #docregion d1 + +.l-main-section +:marked + ## Data Binding +.l-sub-section + :marked + Applications display data values to a user and respond to user + actions (clicks, touches, keystrokes). + + We could push application data values into HTML, attach + event listeners, pull changed values from the screen, and + update application data values ... all by hand. + + Or we could declare the relationship between an HTML widget + and an application data source ... and let a data binding + framework handle the details. + + Data Binding is that second approach. Angular has a rich + data binding framework with a variety of data binding + operations and supporting declaration syntax. + + The many forms of binding include: + * [Interpolation](template-syntax.html#interpolation) + * [Property Binding](template-syntax.html#property-binding) + * [Event Binding](template-syntax.html#event-binding) + * [Attribute Binding](template-syntax.html#attribute-binding) + * [Class Binding](template-syntax.html#class-binding) + * [Style Binding](template-syntax.html#style-binding) + * [Two-way data binding with ngModel](template-syntax.html#ng-model) + + Learn more about data binding in the + [Template Syntax](template-syntax.html#data-binding) chapter. + +// #enddocregion d1 + +:marked + ## Decorator | Decoration +.l-sub-section + :marked + A Decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments. + + Decorators are a JavaScript language [feature](https://github.com/wycats/javascript-decorators), implemented in TypeScript and proposed for ES2016 (AKA ES7). + + We apply a decorator by positioning it + immediately above or to the left of the thing it decorates. + + Angular has its own set of decorators to help it interoperate with our application parts. + Here is an example of a `@Component` decorator that identifies a + class as an Angular [Component](#component) and an `@Input` decorator applied to a property + of that component. + The elided object argument to the `@Component` decorator would contain the pertinent component metadata. + ``` + @Component({...}) + export class AppComponent { + constructor(@Inject('SpecialFoo') public foo:Foo) {} + @Input() + name:string; + } + ``` + The scope of a decorator is limited to the language feature + that it decorates. None of the decorations shown here will "leak" to other + classes appearing below it in the file. + + .alert.is-important + :marked + Always include the parentheses `()` when applying a decorator. + A decorator is a **function** that must be called when applied. + +// #docregion d2 +:marked + ## Dependency Injection +.l-sub-section + :marked + Dependency Injection is both a design pattern and a mechanism + for creating and delivering parts of an application to other + parts of an application that request them. + + Angular developers prefer to build applications by defining many simple parts + that each do one thing well and then wire them together at runtime. + + These parts often rely on other parts. An Angular [Component](#component) + part might rely on a service part to get data or perform a calculation. When a + part "A" relies on another part "B", we say that "A" depends on "B" and + that "B" is a dependency of "A". + + We can ask a "Dependency Injection System" to create "A" + for us and handle all the dependencies. + If "A" needs "B" and "B" needs "C", the system resolves that chain of dependencies + and returns a fully prepared instance of "A". + + Angular provides and relies upon its own sophisticated + [Dependency Injection](dependency-injection.html) system + to assemble and run applications by "injecting" application parts + into other application parts where and when needed. + + At the core is an [`Injector`](#injector) that returns dependency values on request. + The expression `injector.get(token)` returns the value associated with the given token. + + A token is an Angular type (`OpaqueToken`). We rarely deal with tokens directly; most + methods accept a class name (`Foo`) or a string ("foo") and Angular converts it + to a token. When we write `injector.get(Foo)`, the injector returns + the value associated with the token for the `Foo` class, typically an instance of `Foo` itself. + + Angular makes similar requests internally during many of its operations + as when it creates a [`Component`](#AppComponent) for display. + + The `Injector` maintains an internal map of tokens to dependency values. + If the `Injector` can't find a value for a given token, it creates + a new value using a `Provider` for that token. + + A [Provider](#provider) is a recipe for + creating new instances of a dependency value associated with a particular token. + + An injector can only create a value for a given token if it has + a `Provider` for that token in its internal provider registry. + Registering providers is a critical preparatory step. + + Angular registers some of its own providers with every injector. + We can register our own providers. Quite often the best time to register a `Provider` + is when we [bootstrap](#bootstrap) the application. + There are other opportunities to register as well. + + Learn more in the [Dependency Injection](dependency-injection.html) chapter. +:marked + ## Directive +.l-sub-section + :marked + An Angular class responsible for creating, re-shaping, and interacting with HTML elements + in the browser DOM. Directives are Angular's most fundamental feature. + + A Directive is almost always associated with an HTML element or attribute. + We often refer to such an element or attribute as the directive itself. + When Angular finds a directive in an HTML template, + it creates the matching directive class instance + and gives that instance control over that portion of the browser DOM. + + Developers can invent custom HTML markup (e.g., ``) to + associate with their custom directives. They add this custom markup to HTML templates + as if they were writing native HTML. In this way, directives become extensions of + HTML itself. + + Directives fall into one of three categories: + + 1. [Components](#component) that combine application logic with an HTML template to + render application [views]. Components are usually represented as HTML elements. + They are the building blocks of an Angular application and the + developer can expect to write a lot of them. + + 1. [Attribute Directives](#attribute-directive) that can listen to and modify the behavior of + other HTML elements, attributes, properties, and components. They are usually represented + as HTML attributes, hence the name. + + 1. [Structural Directives](#structural-directive), a directive responsible for + shaping or re-shaping HTML layout, typically by adding, removing, or manipulating + elements and their children. +// #enddocregion d2 + +// #docregion e1 + +// #enddocregion e1 +// #docregion e2 +.l-main-section +:marked + ## ECMAScript +.l-sub-section + :marked + The [official JavaScript language specification](https://en.wikipedia.org/wiki/ECMAScript). + + The latest approved version of JavaScript is + [ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/) + (AKA "ES2015" or "ES6") and many Angular 2 developers will write their applications + either in this version of the language or a dialect that strives to be + compatible with it such as [TypeScript](#typesScript). + + Most modern browsers today only support the prior "ECMAScript 5" (AKA ES5) standard. + Applications written in ES2015 or one of its dialects must be "[transpiled](#transpile)" + to ES5 JavaScript. + + Angular 2 developers may choose to write in ES5 directly. +:marked + ## ECMAScript 2015 +.l-sub-section + :marked + The lastest released version of JavaScript, + [ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/) + (AKA "ES2015" or "ES6") +:marked + ## ES2015 +.l-sub-section + :marked + Short hand for "[ECMAScript 2015](#ecmascript=2015)". +:marked + ## ES6 +.l-sub-section + :marked + Short hand for "[ECMAScript 2015](#ecmascript=2015)". +:marked + ## ES5 +.l-sub-section + :marked + Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers. + See [ECMAScript](#ecmascript). +// #enddocregion e2 + +// #docregion f-l + + + + +.l-main-section +:marked + ## Injector +.l-sub-section + :marked + An object in the Angular [dependency injection system](#dependency-injection) + that can find a named "dependency" in its cache or create such a thing + with a registered [provider](#provider). + +:marked + ## Input +.l-sub-section + :marked + A directive property that can be the ***target*** of a + [Property Binding](template-syntax.html#property-binding). + Data values flow *into* this property from the data source identified + in the template expression to the right of the equal sign. + + See the [Template Syntax](template-syntax.html#inputs-outputs) chapter. + +:marked + ## Interpolation +.l-sub-section + :marked + A form of [Property Data Binding](#data-binding) in which a + [template expression](#template-expression) between double-curly braces + renders as text. That text may be concatenated with neighboring text + before it is assigned to an element property + or displayed between element tags as in this example. + + code-example(language="html" escape="html"). + + + :marked + Learn more about interpolation in the + [Template Syntax](template-syntax.html#interpolation) chapter. + + + + + +.l-main-section +:marked + ## Lifecycle Hooks +.l-sub-section + :marked + [Directives](#directive) and [Components](#component) have a lifecycle + managed by Angular as it creates, updates and destroys them. + + Developers can tap into key moments in that lifecycle by implementing + one or more of the "Lifecycle Hook" interfaces. + + Each interface has a single hook method whose name is the interface name prefixed with `ng`. + For example, the `OnInit` interface has a hook method names `ngOnInit`. + + Angular calls these hook methods in the following order: + * `ngOnChanges` - called when an [input](#input)/[output](#output) binding values change + * `ngOnInit` - after the first `ngOnChanges` + * `ngDoCheck` - developer's custom change detection + * `ngAfterContentInit` - after component content initialized + * `ngAfterContentChecked` - after every check of component content + * `ngAfterViewInit` - after component's view(s) are initialized + * `ngAfterViewChecked` - after every check of a component's view(s) + * `ngOnDestroy` - just before the directive is destroyed. + + Learn more in the [Lifecycle Hooks](lifecycle-hooks.html) chapter. +// #enddocregion f-l + +// #docregion m1 + +// #enddocregion m1 +// #docregion m2 +.l-main-section +:marked + ## Module +.l-sub-section + :marked + Angular apps are modular. + + In general, we assemble our application from many modules, both the ones we write ourselves + and the ones we acquire from others. + + A typical module is a cohesive block of code dedicated to a single purpose. + + A module **exports** something of value in that code, typically one thing such as a class. + A module that needs that thing, **imports** it. + + The structure of Angular modules and the import/export syntax + is based on the [ES2015](#es2015) module standard + described [here](http://www.2ality.com/2014/09/es6-modules-final.html). + + An application that adheres to this standard requires a module loader to + load modules on request and resolve inter-module dependencies. + Angular does not ship with a module loader and does not have a preference + for any particular 3rd party library (although most samples use SystemJS). + Application developers may pick any module library that conforms to the standard + + Modules are typically named after the file in which the exported thing is defined. + The Angular [DatePipe](https://github.com/angular/angular/blob/master/modules/angular2/src/common/pipes/date_pipe.ts) + class belongs to a feature module named `date_pipe` in the file `date_pipe.ts`. + + Developers rarely access Angular feature modules directly. + We usually import them from public-facing **library modules** + called [**barrels**](#barrel). Barrels are groups of logically related modules. + The `angular2/core` barrel is a good example. + + Learn more in "[Modules, barrels and bundles](https://github.com/angular/angular/blob/master/modules/angular2/docs/bundles/overview.md)". +// #enddocregion m2 + +// #docregion n-s +- var lang = current.path[1] +- var decorator = lang = 'dart' ? 'annotation' : '[decorator](#decorator)' +- var atSym = lang == 'js' ? '' : '@' + + +.l-main-section +:marked + ## Output +.l-sub-section + :marked + A directive property that can be the ***target*** of an + [Event Binding](template-syntax.html#property-binding). + Events stream *out* of this property to the receiver identified + in the template expression to the right of the equal sign. + + See the [Template Syntax](template-syntax.html#inputs-outputs) chapter. + +.l-main-section + +:marked + ## Pipe +.l-sub-section + :marked + An Angular pipe is a function that transforms input values to output values for + display in a [view](#view). We use the `#{atSym}Pipe` #{decorator} + to associate the pipe function with a name. We then can use that + name in our HTML to declaratively transform values on screen. + + Here's an example that uses the built-in `currency` pipe to display + a numeric value in the local currency. + + code-example(language="html" escape="html"). + {{product.price | currency}} + :marked + Learn more in the chapter on [pipes](pipes.html) . + +:marked + ## Provider +.l-sub-section + :marked + A Provider creates a new instance of a dependency for the Dependency Injection system. + It relates a lookup token to code - sometimes called a "recipe" - that can create a dependency value. + + For example, `new Provider(Foo, {useClass: Foo})` creates a `Provider` + that relates the `Foo` token to a function that creates a new instance of the `Foo` class. + + There are other ways to create tokens and recipes. + See [Dependency Injection](#dependency-injection) chapter to learn more. + +.l-main-section + + +:marked + ## Router +.l-sub-section + :marked + Most applications consist of many screens or [views](#view). + The user navigates among them by clicking links and buttons + and taking other similar actions that cause the application to + replace one view with another. + + The Angular [Component Router](router.html) is a richly featured mechanism for configuring + and managing the entire view navigation process including the creation and destruction + of views. +:marked + ## Routing Component +.l-sub-section + :marked + A [Component](#component) with an attached router. + + In most cases, the component became attached to a [router](#router) by means + of a `#{atSym}RouterConfig` #{decorator} that defined routes to views controlled by this component. + + The component's template has a `RouterOutlet` element where it can display views produced by the router. + + It likely has anchor tags or buttons with `RouterLink` directives that users can click to navigate. + + +.l-main-section +:marked + ## Structural Directive +.l-sub-section + :marked + A category of [Directive](#directive) that can + shape or re-shape HTML layout, typically by adding, removing, or manipulating + elements and their children. + + The `ngIf` "conditional element" directive and the `ngFor` "repeater" directive are + good examples in this category. +// #enddocregion n-s + +// #docregion t1 + +.l-main-section +:marked + ## Template +.l-sub-section + :marked + A template is a chunk of HTML that Angular uses to render a [view](#view) with + the support and continuing guidance of an Angular [Directive](#directive), + most notably a [Component](#component). + + We write templates in a special [Template Syntax](template-syntax.html). + +:marked + ## Template Expression +.l-sub-section + :marked + An expression in a JavaScript-like syntax that Angular evaluates within + a [data binding](#data-binding). Learn how to write template expressions + in the [Template Syntax](template-syntax.html#template-expressions) chapter. + +// #enddocregion t1 +// #docregion t2 +:marked + ## Transpile +.l-sub-section + :marked + The process of transforming code written in one form of JavaScript + (e.g., TypeScript) into another form of JavaScript (e.g., [ES5](#es5)). + + :marked + ## TypeScript +.l-sub-section + :marked + A version of JavaScript that supports most [ECMAScript 2015](#ecmascript=2015) + language features and many features that may arrive in future versions + of JavaScript such as [Decorators](#decorator). + + TypeScript is also noteable for its optional typing system which gives + us compile-time type-checking and strong tooling support (e.g. "intellisense", + code completion, refactoring, and intelligent search). Many code editors + and IDEs support TypeScript either natively or with plugins. + + TypeScript is the preferred language for Angular 2 development although + we are welcome to write in other JavaScript dialects such as [ES5](#es5). + + Angular 2 itself is written in TypeScript. + + Learn more about TypeScript on its [website](http://www.typescriptlang.org/). +// #enddocregion t2 + +// #docregion u-z + + +.l-main-section +:marked + ## View +.l-sub-section + :marked + A view is a portion of the screen that displays information and responds + to user actions such as clicks, mouse moves, and keystrokes. + + Angular renders a view under the control of one or more [Directives](#directive), + especially [Component](#component) directives and their companion [Templates](#template). + The Component plays such a prominent role that we often + find it convenient to refer to a component as a view. + + Views often contain other views and any view might be loaded and unloaded + dynamically as the user navigates through the application, typically + under the control of a [router](#router). + +.l-main-section + + + + +:marked + ## Zone +.l-sub-section + :marked + Zones are a mechanism for encapsulating and intercepting + a JavaScript application's asynchronous activity. + + The browser DOM and JavaScript have a limited number + of asynchronous activities, activities such as DOM events (e.g., clicks), + [promises](#promise), and + [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) + calls to remote servers. + + Zones intercept all of these activities and give a "zone client" the opportunity + to take action before and after the async activity completes. + + Angular runs our application in a zone where it can respond to + asynchronous events by checking for data changes and updating + the information it displays via [data binding](#data-binding). + + Learn more about zones in this + [Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). +// #enddocregion u-z diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index 33f144cb01..172706aedd 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/public/docs/ts/latest/guide/_data.json @@ -1,54 +1,70 @@ { - "_listtype": "ordered", - "index": { "title": "Documentation Overview", - "nextable":true + "navTitle": "Overview", + "description": "How to read and use this documentation", + "nextable": true, + "basics": true }, "architecture": { "title": "Architecture Overview", + "navTitle": "Architecture", "intro": "The basic building blocks of Angular 2 applications", - "nextable":true + "nextable": true, + "basics": true }, "displaying-data": { "title": "Displaying Data", "intro": "Interpolation and other forms of property binding help us show app data in the UI.", - "nextable":true + "nextable": true, + "basics": true }, "user-input": { "title": "User Input", "intro": "User input triggers DOM events. We listen to those events with event bindings that funnel updated values back into our components and models.", - "nextable":true + "nextable": true, + "basics": true }, "forms": { "title": "Forms", "intro": "A form creates a cohesive, effective, and compelling data entry experience. An Angular form coordinates a set of data-bound user controls, tracks changes, validates input, and presents errors.", - "nextable":true + "nextable": true, + "basics": true }, "dependency-injection": { "title": "Dependency Injection", "intro": "Angular's dependency injection system creates and delivers dependent services \"just-in-time\".", - "nextable":true + "nextable": true, + "basics": true }, "template-syntax": { "title": "Template Syntax", "intro": "Learn how to write templates that display data and consume user events with the help of data binding.", - "nextable":true + "nextable": true, + "basics": true }, + "cheatsheet": { + "title": "Angular Cheat Sheet", + "intro": "A quick quide to Angular syntax.", + "nextable": true, + "basics": true + }, + "attribute-directives": { "title": "Attribute Directives", "intro": "Attribute directives attach behavior to elements." }, "hierarchical-dependency-injection": { - "title": "Hierarchical Injectors", + "title": "Hierarchical Dependency Injectors", + "navTitle": "Hierarchical Injectors", "intro": "Angular's hierarchical dependency injection system supports nested injectors in parallel with the component tree." }, @@ -87,18 +103,19 @@ "intro": "Techniques and practices for testing an Angular 2 app" }, + "typescript-configuration": { + "title": "TypeScript Configuration", + "intro": "TypeScript configuration for Angular 2 developers" + }, + "upgrade": { "title": "Upgrading from 1.x", "intro": "Angular 1 applications can be incrementally upgraded to Angular 2." }, - "typescript-configuration": { - "title": "TypeScript Configuration", - "intro": "TypeScript configuration for Angular 2 developers" - }, - "glossary": { "title": "Glossary", - "intro": "Brief definitions of the most important words in the Angular 2 vocabulary" + "intro": "Brief definitions of the most important words in the Angular 2 vocabulary", + "hide": true } } diff --git a/public/docs/ts/latest/guide/cheatsheet.jade b/public/docs/ts/latest/guide/cheatsheet.jade index fbc72411e3..ff8cc6085c 100644 --- a/public/docs/ts/latest/guide/cheatsheet.jade +++ b/public/docs/ts/latest/guide/cheatsheet.jade @@ -1,6 +1 @@ -.banner - p.text-body This cheat sheet is provisional and may change. Angular 2 is currently in Beta. - -article(class="l-content-small grid-fluid docs-content") - .cheatsheet - ngio-cheatsheet(src='./cheatsheet.json') +!= partial("../cheatsheet") diff --git a/public/docs/ts/latest/guide/glossary.jade b/public/docs/ts/latest/guide/glossary.jade index 2e94bfd7a0..a66284569e 100644 --- a/public/docs/ts/latest/guide/glossary.jade +++ b/public/docs/ts/latest/guide/glossary.jade @@ -1,637 +1 @@ -include ../_util-fns - -// #docregion intro -:marked - # Angular 2 Glossary - - Angular 2 has a vocabulary of its own. - Most Angular 2 terms are everyday English words - with a specific meaning within the Angular system. - - We have gathered here the most prominent terms - and a few less familiar ones that have unusual or - unexpected definitions. - - [A](#A) [B](#B) [C](#C) [D](#D) [E](#E) [F](#F) [G](#G) [H](#H) [I](#I) - [J](#J) [K](#K) [L](#L) [M](#M) [N](#N) [O](#O) [P](#P) [Q](#Q) [R](#R) - [S](#S) [T](#T) [U](#U) [V](#V) [W](#W) [X](#X) [Y](#Y) [Z](#Z) -// #enddocregion intro - -// #docregion a1 - -// #enddocregion a1 -.l-main-section -:marked - ## Annotation -.l-sub-section - :marked - In practice a synonym for [Decoration](#decorator). -// #enddocregion a-1 -// #docregion a-2 -:marked - ## Attribute Directive -.l-sub-section - :marked - A category of [Directive](#directive) that can listen to and modify the behavior of - other HTML elements, attributes, properties, and components. They are usually represented - as HTML attributes, hence the name. - - The `ngClass` directive for adding and removing CSS class names is a good example of - an Attribute Directive. -// #enddocregion a-2 - -// #docregion b-c -- var lang = current.path[1] -- var decorator = lang = 'dart' ? 'annotation' : '[decorator](#decorator)' -- var atSym = lang == 'js' ? '' : '@' - -.l-main-section -:marked - ## Barrel -.l-sub-section - :marked - A **barrel** is an Angular library module consisting of a logical grouping of single-purpose modules - such as `Component` and `Directive`. - - Familiar barrels include `angular2/core`, `angular2/common`, `angular2/platform/browser`, - `angular2/http`, and `angular2/router`. - - Barrels are packaged and shipped as [**bundles**](#bundle) that - we may load with script tags in our `index.html`. - - The script, `angular2.dev.js`, is a bundle. - - Learn more in "[Modules, barrels and bundles](https://github.com/angular/angular/blob/master/modules/angular2/docs/bundles/overview.md)". - -:marked - ## Binding -.l-sub-section - :marked - Almost always refers to [Data Binding](#data-binding) and the act of - binding an HTML object property to a data object property. - - May refer to a [Dependency Injection](#dependency-injection) binding - between a "token" or "key" and a dependency [provider](#provider). - This more rare usage should be clear in context. - -:marked - ## Bootstrap -.l-sub-section - :marked - We launch an Angular application by "bootstrapping" it with the `bootstrap` method. - The `bootstrap` method identifies an application's top level "root" [Component](#component) - and optionally registers service [providers](#provider) with the - [dependency injection system](#dependency-injection). - - One can bootstrap multiple apps in the same `index.html`, each with its own top level root. - -:marked - ## Bundle -.l-sub-section - :marked - Angular JavaScript libraries are shipped in **bundles** within an **npm package** - such as [angular2](https://www.npmjs.com/package/angular2). - - The scripts `angular2.dev.js`, `http.js`, `router.js`, and `Rx.js` are - familiar examples of bundles. - - A bundle contains one more more [**barrels**](#barrel) - and each barrel contains a collection of logically related [modules](#module) - - Familiar barrels include `angular2/core`, `angular2/common`, `angular2/platform/browser`, - `angular2/http`, `angular2/router`. - - Learn more in "[Modules, barrels and bundles](https://github.com/angular/angular/blob/master/modules/angular2/docs/bundles/overview.md)". - - -.l-main-section -:marked - ## Component -.l-sub-section - :marked - An Angular class responsible for exposing data - to a [View](#view) and handling most of the view’s display - and user-interaction logic. - - The Component is one of the most important building blocks in the Angular system. - It is, in fact, an Angular [Directive](#directive) with a companion [Template](#template). - - The developer applies the `#{atSym}Component` #{decorator} to - the component class, thereby attaching to the class the essential component metadata - that Angular needs to create a component instance and render it with its template - as a view. - - Those familiar with "MVC" and "MVVM" patterns will recognize - the Component in the role of "Controller" or "View Model". -// #enddocregion b-c - -// #docregion d1 - -.l-main-section -:marked - ## Data Binding -.l-sub-section - :marked - Applications display data values to a user and respond to user - actions (clicks, touches, keystrokes). - - We could push application data values into HTML, attach - event listeners, pull changed values from the screen, and - update application data values ... all by hand. - - Or we could declare the relationship between an HTML widget - and an application data source ... and let a data binding - framework handle the details. - - Data Binding is that second approach. Angular has a rich - data binding framework with a variety of data binding - operations and supporting declaration syntax. - - The many forms of binding include: - * [Interpolation](template-syntax.html#interpolation) - * [Property Binding](template-syntax.html#property-binding) - * [Event Binding](template-syntax.html#event-binding) - * [Attribute Binding](template-syntax.html#attribute-binding) - * [Class Binding](template-syntax.html#class-binding) - * [Style Binding](template-syntax.html#style-binding) - * [Two-way data binding with ngModel](template-syntax.html#ng-model) - - Learn more about data binding in the - [Template Syntax](template-syntax.html#data-binding) chapter. - -// #enddocregion d1 - -:marked - ## Decorator | Decoration -.l-sub-section - :marked - A Decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments. - - Decorators are a JavaScript language [feature](https://github.com/wycats/javascript-decorators), implemented in TypeScript and proposed for ES2016 (AKA ES7). - - We apply a decorator by positioning it - immediately above or to the left of the thing it decorates. - - Angular has its own set of decorators to help it interoperate with our application parts. - Here is an example of a `@Component` decorator that identifies a - class as an Angular [Component](#component) and an `@Input` decorator applied to a property - of that component. - The elided object argument to the `@Component` decorator would contain the pertinent component metadata. - ``` - @Component({...}) - export class AppComponent { - constructor(@Inject('SpecialFoo') public foo:Foo) {} - @Input() - name:string; - } - ``` - The scope of a decorator is limited to the language feature - that it decorates. None of the decorations shown here will "leak" to other - classes appearing below it in the file. - - .alert.is-important - :marked - Always include the parentheses `()` when applying a decorator. - A decorator is a **function** that must be called when applied. - -// #docregion d2 -:marked - ## Dependency Injection -.l-sub-section - :marked - Dependency Injection is both a design pattern and a mechanism - for creating and delivering parts of an application to other - parts of an application that request them. - - Angular developers prefer to build applications by defining many simple parts - that each do one thing well and then wire them together at runtime. - - These parts often rely on other parts. An Angular [Component](#component) - part might rely on a service part to get data or perform a calculation. When a - part "A" relies on another part "B", we say that "A" depends on "B" and - that "B" is a dependency of "A". - - We can ask a "Dependency Injection System" to create "A" - for us and handle all the dependencies. - If "A" needs "B" and "B" needs "C", the system resolves that chain of dependencies - and returns a fully prepared instance of "A". - - Angular provides and relies upon its own sophisticated - [Dependency Injection](dependency-injection.html) system - to assemble and run applications by "injecting" application parts - into other application parts where and when needed. - - At the core is an [`Injector`](#injector) that returns dependency values on request. - The expression `injector.get(token)` returns the value associated with the given token. - - A token is an Angular type (`OpaqueToken`). We rarely deal with tokens directly; most - methods accept a class name (`Foo`) or a string ("foo") and Angular converts it - to a token. When we write `injector.get(Foo)`, the injector returns - the value associated with the token for the `Foo` class, typically an instance of `Foo` itself. - - Angular makes similar requests internally during many of its operations - as when it creates a [`Component`](#AppComponent) for display. - - The `Injector` maintains an internal map of tokens to dependency values. - If the `Injector` can't find a value for a given token, it creates - a new value using a `Provider` for that token. - - A [Provider](#provider) is a recipe for - creating new instances of a dependency value associated with a particular token. - - An injector can only create a value for a given token if it has - a `Provider` for that token in its internal provider registry. - Registering providers is a critical preparatory step. - - Angular registers some of its own providers with every injector. - We can register our own providers. Quite often the best time to register a `Provider` - is when we [bootstrap](#bootstrap) the application. - There are other opportunities to register as well. - - Learn more in the [Dependency Injection](dependency-injection.html) chapter. -:marked - ## Directive -.l-sub-section - :marked - An Angular class responsible for creating, re-shaping, and interacting with HTML elements - in the browser DOM. Directives are Angular's most fundamental feature. - - A Directive is almost always associated with an HTML element or attribute. - We often refer to such an element or attribute as the directive itself. - When Angular finds a directive in an HTML template, - it creates the matching directive class instance - and gives that instance control over that portion of the browser DOM. - - Developers can invent custom HTML markup (e.g., ``) to - associate with their custom directives. They add this custom markup to HTML templates - as if they were writing native HTML. In this way, directives become extensions of - HTML itself. - - Directives fall into one of three categories: - - 1. [Components](#component) that combine application logic with an HTML template to - render application [views]. Components are usually represented as HTML elements. - They are the building blocks of an Angular application and the - developer can expect to write a lot of them. - - 1. [Attribute Directives](#attribute-directive) that can listen to and modify the behavior of - other HTML elements, attributes, properties, and components. They are usually represented - as HTML attributes, hence the name. - - 1. [Structural Directives](#structural-directive), a directive responsible for - shaping or re-shaping HTML layout, typically by adding, removing, or manipulating - elements and their children. -// #enddocregion d2 - -// #docregion e1 - -// #enddocregion e1 -// #docregion e2 -.l-main-section -:marked - ## ECMAScript -.l-sub-section - :marked - The [official JavaScript language specification](https://en.wikipedia.org/wiki/ECMAScript). - - The latest approved version of JavaScript is - [ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/) - (AKA "ES2015" or "ES6") and many Angular 2 developers will write their applications - either in this version of the language or a dialect that strives to be - compatible with it such as [TypeScript](#typesScript). - - Most modern browsers today only support the prior "ECMAScript 5" (AKA ES5) standard. - Applications written in ES2015 or one of its dialects must be "[transpiled](#transpile)" - to ES5 JavaScript. - - Angular 2 developers may choose to write in ES5 directly. -:marked - ## ECMAScript 2015 -.l-sub-section - :marked - The lastest released version of JavaScript, - [ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/) - (AKA "ES2015" or "ES6") -:marked - ## ES2015 -.l-sub-section - :marked - Short hand for "[ECMAScript 2015](#ecmascript=2015)". -:marked - ## ES6 -.l-sub-section - :marked - Short hand for "[ECMAScript 2015](#ecmascript=2015)". -:marked - ## ES5 -.l-sub-section - :marked - Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers. - See [ECMAScript](#ecmascript). -// #enddocregion e2 - -// #docregion f-l - - - - -.l-main-section -:marked - ## Injector -.l-sub-section - :marked - An object in the Angular [dependency injection system](#dependency-injection) - that can find a named "dependency" in its cache or create such a thing - with a registered [provider](#provider). - -:marked - ## Input -.l-sub-section - :marked - A directive property that can be the ***target*** of a - [Property Binding](template-syntax.html#property-binding). - Data values flow *into* this property from the data source identified - in the template expression to the right of the equal sign. - - See the [Template Syntax](template-syntax.html#inputs-outputs) chapter. - -:marked - ## Interpolation -.l-sub-section - :marked - A form of [Property Data Binding](#data-binding) in which a - [template expression](#template-expression) between double-curly braces - renders as text. That text may be concatenated with neighboring text - before it is assigned to an element property - or displayed between element tags as in this example. - - code-example(language="html" escape="html"). - - - :marked - Learn more about interpolation in the - [Template Syntax](template-syntax.html#interpolation) chapter. - - - - - -.l-main-section -:marked - ## Lifecycle Hooks -.l-sub-section - :marked - [Directives](#directive) and [Components](#component) have a lifecycle - managed by Angular as it creates, updates and destroys them. - - Developers can tap into key moments in that lifecycle by implementing - one or more of the "Lifecycle Hook" interfaces. - - Each interface has a single hook method whose name is the interface name prefixed with `ng`. - For example, the `OnInit` interface has a hook method names `ngOnInit`. - - Angular calls these hook methods in the following order: - * `ngOnChanges` - called when an [input](#input)/[output](#output) binding values change - * `ngOnInit` - after the first `ngOnChanges` - * `ngDoCheck` - developer's custom change detection - * `ngAfterContentInit` - after component content initialized - * `ngAfterContentChecked` - after every check of component content - * `ngAfterViewInit` - after component's view(s) are initialized - * `ngAfterViewChecked` - after every check of a component's view(s) - * `ngOnDestroy` - just before the directive is destroyed. - - Learn more in the [Lifecycle Hooks](lifecycle-hooks.html) chapter. -// #enddocregion f-l - -// #docregion m1 - -// #enddocregion m1 -// #docregion m2 -.l-main-section -:marked - ## Module -.l-sub-section - :marked - Angular apps are modular. - - In general, we assemble our application from many modules, both the ones we write ourselves - and the ones we acquire from others. - - A typical module is a cohesive block of code dedicated to a single purpose. - - A module **exports** something of value in that code, typically one thing such as a class. - A module that needs that thing, **imports** it. - - The structure of Angular modules and the import/export syntax - is based on the [ES2015](#es2015) module standard - described [here](http://www.2ality.com/2014/09/es6-modules-final.html). - - An application that adheres to this standard requires a module loader to - load modules on request and resolve inter-module dependencies. - Angular does not ship with a module loader and does not have a preference - for any particular 3rd party library (although most samples use SystemJS). - Application developers may pick any module library that conforms to the standard - - Modules are typically named after the file in which the exported thing is defined. - The Angular [DatePipe](https://github.com/angular/angular/blob/master/modules/angular2/src/common/pipes/date_pipe.ts) - class belongs to a feature module named `date_pipe` in the file `date_pipe.ts`. - - Developers rarely access Angular feature modules directly. - We usually import them from public-facing **library modules** - called [**barrels**](#barrel). Barrels are groups of logically related modules. - The `angular2/core` barrel is a good example. - - Learn more in "[Modules, barrels and bundles](https://github.com/angular/angular/blob/master/modules/angular2/docs/bundles/overview.md)". -// #enddocregion m2 - -// #docregion n-s -- var lang = current.path[1] -- var decorator = lang = 'dart' ? 'annotation' : '[decorator](#decorator)' -- var atSym = lang == 'js' ? '' : '@' - - -.l-main-section -:marked - ## Output -.l-sub-section - :marked - A directive property that can be the ***target*** of an - [Event Binding](template-syntax.html#property-binding). - Events stream *out* of this property to the receiver identified - in the template expression to the right of the equal sign. - - See the [Template Syntax](template-syntax.html#inputs-outputs) chapter. - -.l-main-section - -:marked - ## Pipe -.l-sub-section - :marked - An Angular pipe is a function that transforms input values to output values for - display in a [view](#view). We use the `#{atSym}Pipe` #{decorator} - to associate the pipe function with a name. We then can use that - name in our HTML to declaratively transform values on screen. - - Here's an example that uses the built-in `currency` pipe to display - a numeric value in the local currency. - - code-example(language="html" escape="html"). - {{product.price | currency}} - :marked - Learn more in the chapter on [pipes](pipes.html) . - -:marked - ## Provider -.l-sub-section - :marked - A Provider creates a new instance of a dependency for the Dependency Injection system. - It relates a lookup token to code - sometimes called a "recipe" - that can create a dependency value. - - For example, `new Provider(Foo, {useClass: Foo})` creates a `Provider` - that relates the `Foo` token to a function that creates a new instance of the `Foo` class. - - There are other ways to create tokens and recipes. - See [Dependency Injection](#dependency-injection) chapter to learn more. - -.l-main-section - - -:marked - ## Router -.l-sub-section - :marked - Most applications consist of many screens or [views](#view). - The user navigates among them by clicking links and buttons - and taking other similar actions that cause the application to - replace one view with another. - - The Angular [Component Router](router.html) is a richly featured mechanism for configuring - and managing the entire view navigation process including the creation and destruction - of views. -:marked - ## Routing Component -.l-sub-section - :marked - A [Component](#component) with an attached router. - - In most cases, the component became attached to a [router](#router) by means - of a `#{atSym}RouterConfig` #{decorator} that defined routes to views controlled by this component. - - The component's template has a `RouterOutlet` element where it can display views produced by the router. - - It likely has anchor tags or buttons with `RouterLink` directives that users can click to navigate. - - -.l-main-section -:marked - ## Structural Directive -.l-sub-section - :marked - A category of [Directive](#directive) that can - shape or re-shape HTML layout, typically by adding, removing, or manipulating - elements and their children. - - The `ngIf` "conditional element" directive and the `ngFor` "repeater" directive are - good examples in this category. -// #enddocregion n-s - -// #docregion t1 - -.l-main-section -:marked - ## Template -.l-sub-section - :marked - A template is a chunk of HTML that Angular uses to render a [view](#view) with - the support and continuing guidance of an Angular [Directive](#directive), - most notably a [Component](#component). - - We write templates in a special [Template Syntax](template-syntax.html). - -:marked - ## Template Expression -.l-sub-section - :marked - An expression in a JavaScript-like syntax that Angular evaluates within - a [data binding](#data-binding). Learn how to write template expressions - in the [Template Syntax](template-syntax.html#template-expressions) chapter. - -// #enddocregion t1 -// #docregion t2 -:marked - ## Transpile -.l-sub-section - :marked - The process of transforming code written in one form of JavaScript - (e.g., TypeScript) into another form of JavaScript (e.g., [ES5](#es5)). - - :marked - ## TypeScript -.l-sub-section - :marked - A version of JavaScript that supports most [ECMAScript 2015](#ecmascript=2015) - language features and many features that may arrive in future versions - of JavaScript such as [Decorators](#decorator). - - TypeScript is also noteable for its optional typing system which gives - us compile-time type-checking and strong tooling support (e.g. "intellisense", - code completion, refactoring, and intelligent search). Many code editors - and IDEs support TypeScript either natively or with plugins. - - TypeScript is the preferred language for Angular 2 development although - we are welcome to write in other JavaScript dialects such as [ES5](#es5). - - Angular 2 itself is written in TypeScript. - - Learn more about TypeScript on its [website](http://www.typescriptlang.org/). -// #enddocregion t2 - -// #docregion u-z - - -.l-main-section -:marked - ## View -.l-sub-section - :marked - A view is a portion of the screen that displays information and responds - to user actions such as clicks, mouse moves, and keystrokes. - - Angular renders a view under the control of one or more [Directives](#directive), - especially [Component](#component) directives and their companion [Templates](#template). - The Component plays such a prominent role that we often - find it convenient to refer to a component as a view. - - Views often contain other views and any view might be loaded and unloaded - dynamically as the user navigates through the application, typically - under the control of a [router](#router). - -.l-main-section - - - - -:marked - ## Zone -.l-sub-section - :marked - Zones are a mechanism for encapsulating and intercepting - a JavaScript application's asynchronous activity. - - The browser DOM and JavaScript have a limited number - of asynchronous activities, activities such as DOM events (e.g., clicks), - [promises](#promise), and - [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) - calls to remote servers. - - Zones intercept all of these activities and give a "zone client" the opportunity - to take action before and after the async activity completes. - - Angular runs our application in a zone where it can respond to - asynchronous events by checking for data changes and updating - the information it displays via [data binding](#data-binding). - - Learn more about zones in this - [Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). -// #enddocregion u-z +!= partial("../glossary") diff --git a/public/docs/ts/latest/testing/first-app-tests.jade b/public/docs/ts/latest/testing/first-app-tests.jade index 0877e4d1a0..f9461efa18 100644 --- a/public/docs/ts/latest/testing/first-app-tests.jade +++ b/public/docs/ts/latest/testing/first-app-tests.jade @@ -100,11 +100,11 @@ pre.prettyprint.lang-bash First, we'll load the JavaScript file that defines the `Hero` class. - ``` - - - ``` - +code-example(format="" language="html"). + <!-- load the application's Hero definition --> + <script src="app/hero.js"></script> + +:marked Next, we'll add an inline script element with the `Hero`tests themselves ``` @@ -222,10 +222,10 @@ figure.image-display ### Update unit-tests.html Next we update the `unit-tests.html` with a reference to our new `hero.spec.ts` file. Delete the inline test code. The revised pertinent HTML looks like this: - - - - +code-example(format="" language="html"). + <script src="app/hero.js"></script> + <script src="app/hero.spec.js"></script> +:marked ### Run and Fail Look over at the browser (live-server will have reloaded it). The browser displays diff --git a/public/docs/ts/latest/testing/jasmine-testing-101.jade b/public/docs/ts/latest/testing/jasmine-testing-101.jade index 1258b6370a..a2941f72ef 100644 --- a/public/docs/ts/latest/testing/jasmine-testing-101.jade +++ b/public/docs/ts/latest/testing/jasmine-testing-101.jade @@ -59,12 +59,12 @@ pre.prettyprint.lang-bash We’ll write our first test with inline JavaScript inside the body tag: - ``` - - ``` + </script> +:marked Now open `unit-tests.html` in a browser and see the Jasmine HTML test output: figure.image-display @@ -85,13 +85,13 @@ figure.image-display :marked The test we wrote is valid TypeScript because any JavaScript is valid TypeScript. But let’s make it more modern with an arrow function: - ``` +code-example(format="" ). it('true is true', () => expect(true).toEqual(true)); - ``` +:marked Now modify `unit-tests.html` to load the script: - ``` - - ``` +code-example(format="" language="html"). + <script src="1st.spec.js"></script> +:marked Hold on! We wrote a TypeScript file but we’re loading a JavaScript file? That’s a reminder that we need to compile our TypeScript test files as we do our TypeScript application files. Do that next. @@ -171,11 +171,11 @@ figure.image-display :marked Let’s add another Jasmine test to `1st.spec.ts` - ``` +code-example(format="" ). it('null is not the same thing as undefined', () => expect(null).not.toEqual(undefined) ); - ``` +:marked You knew that right? Let’s prove it with this test. The browser should refresh after you paste that test, and show: figure.image-display diff --git a/public/docs/ts/latest/testing/testing-an-angular-pipe.jade b/public/docs/ts/latest/testing/testing-an-angular-pipe.jade index c0e198c2e4..8f8e043217 100644 --- a/public/docs/ts/latest/testing/testing-an-angular-pipe.jade +++ b/public/docs/ts/latest/testing/testing-an-angular-pipe.jade @@ -9,7 +9,7 @@ include ../_util-fns We use it our `hero-detail.component.html` template to turn a hero name like “eeny weenie” into “Eeny Weenie” -code-example(format="linenums" language="html" escape="html"). +code-example(format="." language="html" escape="html").

{{hero.name | initCaps}} is {{userName}}'s current super hero!

:marked @@ -66,22 +66,22 @@ code-example(format="" language="html" escape="html"). We are writing an Angular application afterall and we were going to need Angular sooner or later. That time has come. The `InitCapsPiep` clearly depends on Angular as is clear in the first few lines: - ``` +code-example(format=""). import {Pipe} from 'angular2/core'; @Pipe({ name: 'initCaps' }) export class InitCapsPipe { - ``` +:marked **Open** `unit-tests.html` **Find** the `src="../node_modules/systemjs/dist/system.src.js">` **Replace** Step #1 with these two scripts: - ``` - - - - ``` +code-example(format="" language="html"). + <!-- #1. add the system.js and angular libraries --> + <script src="../node_modules/systemjs/dist/system.src.js"></script> + <script src="../node_modules/angular2/bundles/angular2.dev.js"></script> +:marked ## Add another spec file **Create** an *`init-caps-pipe.spec.ts`** next to `init-caps-pipes.ts` in `src/app` @@ -134,13 +134,13 @@ code-example(format="" language="html" escape="html"). Fortunately, we can create a new `Promise` that wraps both import promises and waits for both to finish loading. - ``` +code-example(format=""). // #3. Import the spec files explicitly Promise.all([ System.import('app/hero.spec'), System.import('app/init-caps-pipe.spec') ]) - ``` +:marked Try it. The browser should refresh and show figure.image-display diff --git a/public/docs/ts/latest/tutorial/_data.json b/public/docs/ts/latest/tutorial/_data.json index 9dc557a611..28d02b2ccb 100644 --- a/public/docs/ts/latest/tutorial/_data.json +++ b/public/docs/ts/latest/tutorial/_data.json @@ -1,34 +1,33 @@ { - "_listtype": "ordered", - "index": { "title": "Tutorial: Tour of Heroes", + "navTitle": "Introduction", "intro": "The Tour of Heroes tutorial takes us through the steps of creating an Angular application in TypeScript.", - "nextable":true + "nextable": true }, "toh-pt1": { "title": "The Hero Editor", "intro": "We build a simple hero editor", - "nextable":true + "nextable": true }, "toh-pt2": { "title": "Master/Detail", "intro": "We build a master/detail page with a list of heroes", - "nextable":true + "nextable": true }, "toh-pt3": { "title": "Multiple Components", "intro": "We refactor the master/detail view into separate components", - "nextable":true + "nextable": true }, "toh-pt4": { "title": "Services", "intro": "We create a reusable service to manage our hero data calls", - "nextable":true + "nextable": true }, "toh-pt5": { "title": "Routing", "intro": "We add the Angular Component Router and learn to navigate among the views", - "nextable":true + "nextable": true } } \ No newline at end of file