From d1e6a24987c261e2da6ad5eb225e91e9a1bed462 Mon Sep 17 00:00:00 2001 From: Foxandxss Date: Mon, 4 Jul 2016 17:03:20 +0200 Subject: [PATCH 1/7] chore: add support for multiline annotations in the API --- .../angular.io-package/templates/class.template.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/api-builder/angular.io-package/templates/class.template.html b/tools/api-builder/angular.io-package/templates/class.template.html index 3155d14af4..db2dddc495 100644 --- a/tools/api-builder/angular.io-package/templates/class.template.html +++ b/tools/api-builder/angular.io-package/templates/class.template.html @@ -76,7 +76,7 @@ div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="80" flex-xs="100") {%- for decorator in doc.decorators %} pre.prettyprint.no-bg - code(class="api-doc-code") + code(class="api-doc-code"). @{$ decorator.name $}{$ paramList(decorator.arguments) | indent(10, false) $} :marked {%- if not decorator.notYetDocumented %} From e4c5fe32e7f1e1bf397e5a10ab7cba2c5ab7c8d3 Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Mon, 4 Jul 2016 15:07:12 -0700 Subject: [PATCH 2/7] docs(forms): fix import in sample HeroFormsComponent - @angular/common -> @angular/forms --- public/docs/_examples/forms/ts/app/hero-form.component.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/docs/_examples/forms/ts/app/hero-form.component.ts b/public/docs/_examples/forms/ts/app/hero-form.component.ts index 7ea7c44738..e1a19c5cd9 100644 --- a/public/docs/_examples/forms/ts/app/hero-form.component.ts +++ b/public/docs/_examples/forms/ts/app/hero-form.component.ts @@ -2,7 +2,7 @@ // #docregion // #docregion first, final import { Component } from '@angular/core'; -import { NgForm } from '@angular/common'; +import { NgForm } from '@angular/forms'; import { Hero } from './hero'; From e766f666bd30c68dd3c486af59770ce04af76f11 Mon Sep 17 00:00:00 2001 From: Stephen Fox Date: Fri, 17 Jun 2016 17:23:35 -0600 Subject: [PATCH 3/7] docs(http): Small typo fix in sentence reference to items: Observable Ward tacked on router: ngDestroy -> ngOnDestroy closes #1690 --- public/docs/ts/latest/guide/router.jade | 2 +- public/docs/ts/latest/guide/server-communication.jade | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/public/docs/ts/latest/guide/router.jade b/public/docs/ts/latest/guide/router.jade index 9b7e260093..c3d6d3a7ec 100644 --- a/public/docs/ts/latest/guide/router.jade +++ b/public/docs/ts/latest/guide/router.jade @@ -739,7 +739,7 @@ h4#snapshot Snapshot: the no-observable alternative be re-used. We'll always re-create the component each time we navigate to it. The router offers a *Snapshot* alternative that gives us the initial value of the route parameters. - We don't need to subscribe. We don't have to unsubscribe in `ngDestroy`. + We don't need to subscribe. We don't have to unsubscribe in `ngOnDestroy`. It's much simpler to write and read: +makeExample('router/ts/app/heroes/hero-detail.component.2.ts','snapshot')(format=".") .l-sub-section diff --git a/public/docs/ts/latest/guide/server-communication.jade b/public/docs/ts/latest/guide/server-communication.jade index 2ce647af77..602cf6c741 100644 --- a/public/docs/ts/latest/guide/server-communication.jade +++ b/public/docs/ts/latest/guide/server-communication.jade @@ -540,7 +540,7 @@ block wikipedia-jsonp+ The component presents an `` element *search box* to gather search terms from the user. and calls a `search(term)` method after each `keyup` event. - The `search(term)` method delegates to our `WikipediaService` which returns an observable array of string results (`Observable`). Instead of subscribing to the observable inside the component as we did in the `HeroListComponent`, we forward the observable result to the template (via `items`) where the [async pipe](pipes.html#async-pipe) in the `ngFor` handles the subscription. From e2cd8ffe1d00837f2a0b9fe233bca76d004f92c1 Mon Sep 17 00:00:00 2001 From: eltronix Date: Fri, 1 Jul 2016 16:46:10 +0300 Subject: [PATCH 4/7] docs(testing): Fixed typo in pipe.jade closes #1805 --- public/docs/ts/latest/testing/testing-an-angular-pipe.jade | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 fbbe2f13e5..d98845e571 100644 --- a/public/docs/ts/latest/testing/testing-an-angular-pipe.jade +++ b/public/docs/ts/latest/testing/testing-an-angular-pipe.jade @@ -13,7 +13,7 @@ include ../_util-fns We already know *exactly* what we want the `uppercase` pipe to do. We could say our ...expectations... of it are very well defined. - We always use expectations our expectations to guide development, but sometimes it's hard to see the forest for the trees when we're right in the middle of coding. This is especially evident in larger tasks. + We always use our expectations to guide development, but sometimes it's hard to see the forest for the trees when we're right in the middle of coding. This is especially evident in larger tasks. So one thing we can do is put those expectations down as cold hard test code. We were going to test things manually anyway, so doing it *before* we have even one line of code isn't going to hurt. From b0e0d94b5c4e9f458a30c4259917264fd1479402 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 3 Jul 2016 17:11:17 -0700 Subject: [PATCH 5/7] docs: revert Jade to markdown closes #1818 Previously, the markdown of some chapters was converted to Jade markup to support the conditional exclusion of TS prose parts in Dart chapters. This commit reverts some of that back to clean markdown, thanks to a few custom directives. --- public/_includes/_scripts-include.jade | 4 + public/docs/dart/latest/_util-fns.jade | 2 + .../latest/guide/dependency-injection.jade | 14 --- .../latest/guide/server-communication.jade | 21 +--- public/docs/dart/latest/tutorial/index.jade | 3 - public/docs/dart/latest/tutorial/toh-pt1.jade | 3 +- public/docs/dart/latest/tutorial/toh-pt2.jade | 8 +- public/docs/dart/latest/tutorial/toh-pt3.jade | 4 +- public/docs/dart/latest/tutorial/toh-pt4.jade | 2 +- public/docs/dart/latest/tutorial/toh-pt5.jade | 7 +- public/docs/ts/latest/_util-fns.jade | 2 + .../ts/latest/guide/attribute-directives.jade | 3 +- .../ts/latest/guide/component-styles.jade | 2 +- .../ts/latest/guide/dependency-injection.jade | 23 ++-- .../hierarchical-dependency-injection.jade | 2 +- .../docs/ts/latest/guide/lifecycle-hooks.jade | 14 +-- public/docs/ts/latest/guide/pipes.jade | 22 ++-- public/docs/ts/latest/guide/security.jade | 2 +- .../ts/latest/guide/server-communication.jade | 117 ++++++++++-------- .../latest/guide/structural-directives.jade | 2 +- .../docs/ts/latest/guide/template-syntax.jade | 3 +- public/docs/ts/latest/quickstart.jade | 25 ++-- public/docs/ts/latest/tutorial/index.jade | 5 +- public/docs/ts/latest/tutorial/toh-pt1.jade | 8 +- public/docs/ts/latest/tutorial/toh-pt2.jade | 8 +- public/docs/ts/latest/tutorial/toh-pt3.jade | 4 +- public/docs/ts/latest/tutorial/toh-pt4.jade | 6 +- public/docs/ts/latest/tutorial/toh-pt5.jade | 8 +- public/docs/ts/latest/tutorial/toh-pt6.jade | 8 +- public/resources/js/directives/if-docs.js | 25 ++++ .../resources/js/directives/live-example.js | 54 ++++++++ .../resources/js/directives/ngio-ex-path.js | 38 ++++++ public/resources/js/util.js | 87 +++++++++++++ 33 files changed, 366 insertions(+), 170 deletions(-) create mode 100644 public/resources/js/directives/if-docs.js create mode 100644 public/resources/js/directives/live-example.js create mode 100644 public/resources/js/directives/ngio-ex-path.js create mode 100644 public/resources/js/util.js diff --git a/public/_includes/_scripts-include.jade b/public/_includes/_scripts-include.jade index a0b98972f9..9b4cd8048b 100644 --- a/public/_includes/_scripts-include.jade +++ b/public/_includes/_scripts-include.jade @@ -21,6 +21,7 @@ script(src="https://ajax.googleapis.com/ajax/libs/angular_material/1.0.0/angular script(src="/resources/js/site.js") +script(src="/resources/js/util.js") script(src="/resources/js/controllers/app-controller.js") script(src="/resources/js/controllers/resources-controller.js") script(src="/resources/js/directives/cheatsheet.js") @@ -32,6 +33,9 @@ script(src="/resources/js/directives/copy.js") script(src="/resources/js/directives/code-tabs.js") script(src="/resources/js/directives/code-pane.js") script(src="/resources/js/directives/code-example.js") +script(src="/resources/js/directives/if-docs.js") +script(src="/resources/js/directives/live-example.js") +script(src="/resources/js/directives/ngio-ex-path.js") script(src="/resources/js/directives/scroll-y-offset-element.js") diff --git a/public/docs/dart/latest/_util-fns.jade b/public/docs/dart/latest/_util-fns.jade index 5d54cf117d..cc59d49fb5 100644 --- a/public/docs/dart/latest/_util-fns.jade +++ b/public/docs/dart/latest/_util-fns.jade @@ -20,12 +20,14 @@ include ../../../_includes/_util-fns - var _indexHtmlDir = 'web'; - var _mainDir = 'web'; +//- Deprecated mixin liveExampleLink(linkText, exampleUrlPartName) - var text = linkText || 'live example'; - var ex = exampleUrlPartName || getExampleName(); - var href = 'http://angular-examples.github.io/' + ex; a(href='#{href}' target="_blank")= text +//- Deprecated mixin liveExampleLink2(linkText, exampleUrlPartName) - var srcText = attributes.srcText || 'view source'; - var ex = exampleUrlPartName || attributes.example || getExampleName(); diff --git a/public/docs/dart/latest/guide/dependency-injection.jade b/public/docs/dart/latest/guide/dependency-injection.jade index aaef0260d9..ad695a9732 100644 --- a/public/docs/dart/latest/guide/dependency-injection.jade +++ b/public/docs/dart/latest/guide/dependency-injection.jade @@ -10,21 +10,12 @@ block ctor-syntax We also leveraged Dart's constructor syntax for declaring parameters and initializing properties simultaneously. -block service-in-its-own-file - //- N/A - -block one-class-per-file-ts-tradeoffs - //- N/A - block injectable-not-always-needed-in-ts //- The [Angular 2 Dart Transformer](https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer) //- generates static code to replace the use of dart:mirrors. It requires that types be //- identified as targets for static code generation. Generally this is achieved //- by marking the class as @Injectable (though there are other mechanisms). -block ts-any-decorator-will-do - //- N/A - block always-include-paren :marked Always write `@Injectable()`, not just `@Injectable`. @@ -43,11 +34,6 @@ block real-logger A real implementation would probably use the [logging package](https://pub.dartlang.org/packages/logging). -block canonical-provider-expr - |  that creates a new instance of the  - a(href="../api/core/Provider-class.html") Provider - |  class: - block provider-ctor-args - var _secondParam = 'named parameter, such as useClass' :marked diff --git a/public/docs/dart/latest/guide/server-communication.jade b/public/docs/dart/latest/guide/server-communication.jade index 116790bcfa..1c3ad3155c 100644 --- a/public/docs/dart/latest/guide/server-communication.jade +++ b/public/docs/dart/latest/guide/server-communication.jade @@ -8,16 +8,9 @@ block includes - var _Angular_http_library = 'Dart http library' block demos-list - li #[a(href="#http-client") HTTP client: Tour of Heroes] - li #[a(href="#cors") JSONP client: Wikipedia to fetch data from a service that does not support CORS] #[b (under development)] - -block rxjs-import - //- N/A - -block http-client - -block system-config-of-http - //- N/A + :marked + - [HTTP client: Tour of Heroes](#http-client) + - [JSONP client: Wikipedia to fetch data from a service that does not support CORS (**under development**)](#cors) block http-providers :marked @@ -50,9 +43,6 @@ block getheroes-and-addhero programming in Dart, or the tutorial on [_Asynchronous Programming: Futures_](https://www.dartlang.org/docs/tutorials/futures/). -block rxjs - //- N/A - block parse-json :marked The response data are in JSON string form. @@ -65,7 +55,7 @@ block error-handling block hlc-error-handling :marked Back in the `HeroListComponent`, we wrapped our call to - `#{_priv}heroService.getHeroes()` in a `try` clause. When an exception is + `!{_priv}heroService.getHeroes()` in a `try` clause. When an exception is caught, the `errorMessage` variable — which we've bound conditionally in the template — gets assigned to. @@ -75,9 +65,6 @@ block hero-list-comp-add-hero awaits for the *service's* asynchronous `addHero()` to return, and when it does, the new hero is added to the `heroes` list for presentation to the user. -block promises - //- N/A - block wikipedia-jsonp+ :marked Wikipedia offers a modern `CORS` API and a legacy `JSONP` search API. diff --git a/public/docs/dart/latest/tutorial/index.jade b/public/docs/dart/latest/tutorial/index.jade index 4cceeeb572..f18795e25e 100644 --- a/public/docs/dart/latest/tutorial/index.jade +++ b/public/docs/dart/latest/tutorial/index.jade @@ -1,8 +1,5 @@ include ../_util-fns +includeShared('{ts}', 'intro') - -p Run the #[+liveExampleLink2('', 'toh-5')]. - +includeShared('{ts}', 'main') diff --git a/public/docs/dart/latest/tutorial/toh-pt1.jade b/public/docs/dart/latest/tutorial/toh-pt1.jade index 6c86b4d6ae..218d35c788 100644 --- a/public/docs/dart/latest/tutorial/toh-pt1.jade +++ b/public/docs/dart/latest/tutorial/toh-pt1.jade @@ -33,7 +33,8 @@ include ../_util-fns .callout.is-helpful header Source code - p Run the #[+liveExampleLink2('', 'toh-1')] for this part. + :marked + Run the for this part. :marked ## Keep the app compiling and running diff --git a/public/docs/dart/latest/tutorial/toh-pt2.jade b/public/docs/dart/latest/tutorial/toh-pt2.jade index 5fe537ddbc..24e38e31b3 100644 --- a/public/docs/dart/latest/tutorial/toh-pt2.jade +++ b/public/docs/dart/latest/tutorial/toh-pt2.jade @@ -6,8 +6,8 @@ include ../_util-fns We’ll expand our Tour of Heroes app to display a list of heroes, allow the user to select a hero, and display the hero’s details. -p Run the #[+liveExampleLink2('', 'toh-2')] for this part. -:marked + Run the for this part. + Let’s take stock of what we’ll need to display a list of heroes. First, we need a list of heroes. We want to display those heroes in the view’s template, so we’ll need a way to do that. @@ -294,8 +294,8 @@ code-example(language="bash"). * We added the ability to select a hero and show the hero’s details * We learned how to use the built-in directives `ngIf` and `ngFor` in a component’s template -p Run the #[+liveExampleLink2('', 'toh-2')] for this part. -:marked + Run the for this part. + ### The Road Ahead Our Tour of Heroes has grown, but it’s far from complete. We can't put the entire app into a single component. diff --git a/public/docs/dart/latest/tutorial/toh-pt3.jade b/public/docs/dart/latest/tutorial/toh-pt3.jade index 25653aff27..87c061630d 100644 --- a/public/docs/dart/latest/tutorial/toh-pt3.jade +++ b/public/docs/dart/latest/tutorial/toh-pt3.jade @@ -4,7 +4,7 @@ include ../_util-fns Our app is growing. Use cases are flowing in for reusing components, passing data to components, and creating more reusable assets. Let's separate the heroes list from the hero details and make the details component reusable. -p Run the #[+liveExampleLink2('', 'toh-3')] for this part. + Run the for this part. .l-main-section :marked @@ -240,7 +240,7 @@ code-example(format=".") * We learned to bind a parent component to a child component. * We learned to declare the application directives we need in a `directives` list. -p Run the #[+liveExampleLink2('', 'toh-3')] for this part. + Run the for this part. .l-main-section :marked diff --git a/public/docs/dart/latest/tutorial/toh-pt4.jade b/public/docs/dart/latest/tutorial/toh-pt4.jade index b6d090ba8e..cc417c159e 100644 --- a/public/docs/dart/latest/tutorial/toh-pt4.jade +++ b/public/docs/dart/latest/tutorial/toh-pt4.jade @@ -15,7 +15,7 @@ include ../_util-fns Because data services are invariably asynchronous, we'll finish the chapter with a **!{_Promise}**-based version of the data service. -p Run the #[+liveExampleLink2('', 'toh-4')] for this part. + Run the for this part. .l-main-section :marked diff --git a/public/docs/dart/latest/tutorial/toh-pt5.jade b/public/docs/dart/latest/tutorial/toh-pt5.jade index 4dedf71c17..1c0ab90de8 100644 --- a/public/docs/dart/latest/tutorial/toh-pt5.jade +++ b/public/docs/dart/latest/tutorial/toh-pt5.jade @@ -18,7 +18,7 @@ figure.image-display The [Routing and Navigation](../guide/router.html) chapter covers the router in more detail than we will in this tutorial. -p Run the #[+liveExampleLink2('', 'toh-5')] for this part. + Run the for this part. .l-main-section :marked @@ -653,11 +653,10 @@ figure.image-display .l-main-section :marked ## Application structure and code -p. - Review the sample source code in the #[+liveExampleLink2('', 'toh-5')] for this chapter. + + Review the sample source code in the for this chapter. Verify that we have the following structure: -:marked .filetree .file angular2_tour_of_heroes .children diff --git a/public/docs/ts/latest/_util-fns.jade b/public/docs/ts/latest/_util-fns.jade index e31e48af09..1fae0b83ce 100644 --- a/public/docs/ts/latest/_util-fns.jade +++ b/public/docs/ts/latest/_util-fns.jade @@ -4,12 +4,14 @@ include ../../../_includes/_util-fns - var _docsFor = 'ts'; //- Other values match the defaults. +//- Deprecated mixin liveExampleLink(linkText, exampleUrlPartName) - var text = linkText || 'live example'; - var ex = exampleUrlPartName || getExampleName(); - var href = '/resources/live-examples/' + ex + '/ts/plnkr.html'; a(href='#{href}' target="_blank")= text +//- Deprecated mixin liveExampleLink2(linkText, exampleUrlPartName) //- In Dart this gives 2 links: to the demo and to the source. +liveExampleLink(linkText, exampleUrlPartName) diff --git a/public/docs/ts/latest/guide/attribute-directives.jade b/public/docs/ts/latest/guide/attribute-directives.jade index e6db286405..e6f0db9472 100644 --- a/public/docs/ts/latest/guide/attribute-directives.jade +++ b/public/docs/ts/latest/guide/attribute-directives.jade @@ -11,9 +11,8 @@ block includes * [respond to user-initiated events](#respond-to-user) * [pass values into the directive using data binding](#bindings) -p Try the #[+liveExampleLink2()]. + Try the . -:marked ## Directives overview There are three kinds of directives in Angular: diff --git a/public/docs/ts/latest/guide/component-styles.jade b/public/docs/ts/latest/guide/component-styles.jade index 4c912fe1b5..c87e746a8e 100644 --- a/public/docs/ts/latest/guide/component-styles.jade +++ b/public/docs/ts/latest/guide/component-styles.jade @@ -20,7 +20,7 @@ block includes * [Appendix 1: Inspecting the generated runtime component styles](#inspect-generated-css) * [Appendix 2: Loading Styles with Relative URLs](#relative-urls) -p Run the #[+liveExampleLink2()] of the code shown in this chapter. + Run the of the code shown in this chapter. .l-main-section :marked diff --git a/public/docs/ts/latest/guide/dependency-injection.jade b/public/docs/ts/latest/guide/dependency-injection.jade index 9a29ae61a5..2175d5cf65 100644 --- a/public/docs/ts/latest/guide/dependency-injection.jade +++ b/public/docs/ts/latest/guide/dependency-injection.jade @@ -17,7 +17,7 @@ block includes - [Dependency injection tokens](#dependency-injection-tokens) - [Summary](#summary) -p Run the #[+liveExampleLink2()]. + Run the . .l-main-section#why-di :marked @@ -427,7 +427,7 @@ block injectable-not-always-needed-in-ts fact `InjectableMetadata` #{_decorator}s that identify a class as a target for instantiation by an injector. -block ts-any-decorator-will-do ++ifDocsFor('ts') .l-sub-section :marked Injectors use a class's constructor metadata to determine dependent types as @@ -508,20 +508,25 @@ code-example(format="nocode"). What matters is that the injector has a provider to go to when it needs a `Logger`. //- Dart limitation: the provide function isn't const so it cannot be used in an annotation. -- var __andProvideFn = _docsFor == 'dart' ? '' : 'and provide object literal'; +- var _andProvideFn = _docsFor == 'dart' ? '' : 'and provide object literal'; #provide :marked - ### The *Provider* class !{__andProvideFn} + ### The *Provider* class !{_andProvideFn} :marked We wrote the `providers` #{_array} like this: +makeExample('dependency-injection/ts/app/providers.component.ts','providers-1') -p - | This is actually a short-hand expression for a provider registration - block canonical-provider-expr - |  using a provider object literal with two properties: +:marked + This is actually a short-hand expression for a provider registration + + using a _provider_ object literal with two properties: + + + that creates a new instance of the + [Provider](../api/core/Provider-class.html) class: + +makeExample('dependency-injection/ts/app/providers.component.ts','providers-3') @@ -861,7 +866,7 @@ block dart-map-alternative Framework developers may take this approach when they must acquire services generically and dynamically. -block one-class-per-file-ts-tradeoffs ++ifDocsFor('ts') .l-main-section#one-class-per-file :marked ## Appendix: Why we recommend one class per file diff --git a/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade b/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade index 050a0d69c6..6fcf422eda 100644 --- a/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade +++ b/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade @@ -13,7 +13,7 @@ block includes In this chapter we explore these points and write some code. -p Try the #[+liveExampleLink2()]. + Try the . .l-main-section :marked diff --git a/public/docs/ts/latest/guide/lifecycle-hooks.jade b/public/docs/ts/latest/guide/lifecycle-hooks.jade index b8cf4a2e50..427a1f61ea 100644 --- a/public/docs/ts/latest/guide/lifecycle-hooks.jade +++ b/public/docs/ts/latest/guide/lifecycle-hooks.jade @@ -24,7 +24,7 @@ block includes * [AfterViewInit and AfterViewChecked](#afterview) * [AfterContentInit and AfterContentChecked](#aftercontent) -p Try the #[+liveExampleLink2()]. + Try the . a#hooks-overview .l-main-section @@ -195,14 +195,14 @@ a(id="other-lifecycles") 3rd party libraries might implement their hooks as well in order to give us, the developers, more control over how these libraries are used. -a#the-sample -.l-main-section -h2 Lifecycle exercises -p. - The #[+liveExampleLink()] +.l-main-section#the-sample +:marked + ## Lifecycle exercises + + The demonstrates the lifecycle hooks in action through a series of exercises presented as components under the control of the root `AppComponent`. -:marked + They follow a common pattern: a *parent* component serves as a test rig for a *child* component that illustrates one or more of the lifecycle hook methods. diff --git a/public/docs/ts/latest/guide/pipes.jade b/public/docs/ts/latest/guide/pipes.jade index e6f46f1921..8d7857e09a 100644 --- a/public/docs/ts/latest/guide/pipes.jade +++ b/public/docs/ts/latest/guide/pipes.jade @@ -15,9 +15,9 @@ block includes desire many of the same transformations repeatedly, both within and across many applications. We almost think of them as styles. In fact, we'd like to apply them in our HTML templates as we do styles. -p. + Introducing Angular pipes, a way to write display-value transformations that we can declare in our HTML! - Try the #[+liveExampleLink2()]. + Try the . .l-main-section :marked @@ -168,11 +168,10 @@ figure.image-display Angular built-in pipes are pre-registered. Custom pipes must be registered manually. -p. - If we try the #[+liveExampleLink()], +:marked + If we try the , we can probe its behavior by changing the value and the optional exponent in the template. -:marked ## Power Boost Calculator (extra-credit) It's not much fun updating the template to test our custom pipe. @@ -219,10 +218,10 @@ a#change-detection Here's the `FlyingHeroesPipe` implementation which follows the pattern for custom pipes we saw earlier. +makeExample('pipes/ts/app/flying-heroes.pipe.ts', 'pure', 'app/flying-heroes.pipe.ts')(format='.') -p. - When we run the sample now we see odd behavior (try it in the #[+liveExampleLink()]). - Every hero we add is a flying hero but none of them are displayed. :marked + When we run the sample now we see odd behavior (try it in the ). + Every hero we add is a flying hero but none of them are displayed. + Although we're not getting the behavior we want, Angular isn't broken. It's just using a different change detection algorithm — one that ignores changes to the list or any of its items. @@ -328,11 +327,10 @@ block pure-change We can derive a `FlyingHeroesImpureComponent` that we derive from the `FlyingHeroesComponent`. +makeExample('pipes/ts/app/flying-heroes.component.ts','impure-component','app/flying-heroes.component.ts (FlyingHeroesImpureComponent)')(format='.') -p. +:marked The only substantive change is the pipe. - We can confirm in the #[+liveExampleLink()] that the #[i flying heroes] - display updates as we enter new heroes even when we mutate the - #[code heroes] #{_array}. + We can confirm in the that the _flying heroes_ + display updates as we enter new heroes even when we mutate the `heroes` #{_array}. - var _dollar = _docsFor === 'ts' ? '$' : ''; h3#async-pipe The impure #[i AsyncPipe] diff --git a/public/docs/ts/latest/guide/security.jade b/public/docs/ts/latest/guide/security.jade index e747e381a4..161e34c0e8 100644 --- a/public/docs/ts/latest/guide/security.jade +++ b/public/docs/ts/latest/guide/security.jade @@ -20,7 +20,7 @@ block includes * [HTTP-level Vulnerabilities](#http) * [Auditing Angular Applications](#code-review) -p Try the #[+liveExampleLink2()] of the code shown in this chapter. + Try the of the code shown in this chapter. .l-main-section h2#report-issues Reporting Vulnerabilities diff --git a/public/docs/ts/latest/guide/server-communication.jade b/public/docs/ts/latest/guide/server-communication.jade index 602cf6c741..ada653e58f 100644 --- a/public/docs/ts/latest/guide/server-communication.jade +++ b/public/docs/ts/latest/guide/server-communication.jade @@ -19,41 +19,41 @@ block includes The !{_Angular_http_library} simplifies application programming of the **XHR** and **JSONP** APIs as we'll learn in this chapter covering: -ul - li #[a(href="#http-client") HTTP client sample overview] - li #[a(href="#fetch-data") Fetch data with http.get] - +ifDocsFor('ts') - li #[a(href="#rxjs") RxJS Observable of HTTP Responses] - li #[a(href="#enable-rxjs-operators") Enabling RxJS Operators] - li #[a(href="#extract-data") Extract JSON data] - li #[a(href="#error-handling") Error handling] - li #[a(href="#update") Send data to the server] - +ifDocsFor('ts') - li #[a(href="#promises") Promises instead of observables] - li #[a(href="#cors") Cross-origin requests: Wikipedia example] - +ifDocsFor('ts') - ul - li #[a(href="#search-parameters") Set query string parameters] - li #[a(href="#more-observables") Debounce search term input] - li #[a(href="#in-mem-web-api") Appendix: the in-memory web api service] -p. - We illustrate these topics with code that you can - #[+liveExampleLink2('run live in a browser')]. + - [HTTP client sample overview](#http-client) + - [Fetch data with http.get](#fetch-data) +
  • [RxJS Observable of HTTP Responses](#rxjs)
    • +
  • [Enabling RxJS Operators](#enable-rxjs-operators)
    • + - [Extract JSON data](#extract-data) + - [Error handling](#error-handling) + - [Send data to the server](#update) +
  • [Promises instead of observables](#promises)
    • + - [Cross-origin requests: Wikipedia example](#cors) +
      +
    • [Set query string parameters](#search-parameters)
      • +
    • [Debounce search term input](#more-observables)
      • +
    + - [Appendix: the in-memory web api service](#in-mem-web-api) + + We illustrate these topics with code that you can run live. .l-main-section -h1 Demos -p This chapter describes server communication with the help of the following demos -ul - block demos-list - li #[a(href="#http-client") HTTP client: Tour of Heroes with Observables] - li #[a(href="#promises") HTTP client: Tour of Heroes with #{_Promise}s] - li #[a(href="#cors") JSONP client: Wikipedia to fetch data from a service that does not support CORS] - li #[a(href="#more-observables") JSONP client: Wikipedia using observable operators to reduce server calls] +:marked + # Demos + + This chapter describes server communication with the help of the following demos + +block demos-list + :marked + - [HTTP client: Tour of Heroes with Observables](#http-client) + - [HTTP client: Tour of Heroes with !{_Promise}s](#promises) + - [JSONP client: Wikipedia to fetch data from a service that does not support CORS](#cors) + - [JSONP client: Wikipedia using observable operators to reduce server calls](#more-observables) + :marked These demos are orchestrated by the root `AppComponent` +makeExample('server-communication/ts/app/app.component.ts', null, 'app/app.component.ts') -block rxjs-import ++ifDocsFor('ts') :marked There is nothing remarkable here _except_ for the import of RxJS operators. +makeExample('server-communication/ts/app/app.component.ts', 'import-rxjs')(format='.') @@ -62,23 +62,30 @@ block rxjs-import :marked First, we have to configure our application to use server communication facilities. -.l-main-section -h1#http-providers Providing HTTP Services +.l-main-section#http-providers :marked + # Providing HTTP Services + We use the !{_Angular_Http} client to communicate with a server using a familiar HTTP request/response protocol. - The `#{_Http}` client is one of a family of services in the !{_Angular_http_library}. -block system-config-of-http + The `!{_Http}` client is one of a family of services in the !{_Angular_http_library}. + ++ifDocsFor('ts') .l-sub-section :marked SystemJS knows how to load services from the !{_Angular_http_library} when we import from the `@angular/http` module because we registered that module name in the `system.config` file. + :marked - Before we can use the `#{_Http}` client , we'll have to register it as a service provider with the Dependency Injection system. + Before we can use the `!{_Http}` client , we'll have to register it as a service provider with the Dependency Injection system. + .l-sub-section :marked Learn about providers in the [Dependency Injection](dependency-injection.html) chapter. -p In this demo, we register providers in the #[code bootstrap] method of #[code #[+adjExPath('app/main.ts')]]. +:marked + In this demo, we register providers in the `bootstrap()` method of + app/main.ts. + +makeExample('server-communication/ts/app/main.ts', 'v1', 'app/main.ts (v1)')(format='.') block http-providers @@ -104,9 +111,10 @@ block http-providers Such sleight-of-hand is something the root application component should *not* know about. For this reason, and this reason *only*, we hide it *above* the `AppComponent` in `main.ts`. -.l-main-section -h1#http-client The Tour of Heroes #[i HTTP] Client Demo +.l-main-section#http-client :marked + # The Tour of Heroes _HTTP_ Client Demo + Our first demo is a mini-version of the [tutorial](../tutorial)'s "Tour of Heroes" (ToH) application. This version gets some heroes from the server, displays them in a list, lets us add new heroes, and saves them to the server. We use the !{_Angular_Http} client to communicate via `XMLHttpRequest (XHR)`. @@ -168,10 +176,11 @@ block getheroes-and-addhero :marked With our basic intuitions about the component squared away, we're ready to look inside the `HeroService`. -.l-main-section a#HeroService -h2#fetch-data Fetch data with the #[b HeroService] +.l-main-section#fetch-data :marked + ## Fetch data with the **HeroService** + In many of our previous samples we faked the interaction with the server by returning mock heroes in a service like this one: +makeExample('toh-4/ts/app/hero.service.ts', 'just-get-heroes')(format=".") @@ -184,7 +193,7 @@ h2#fetch-data Fetch data with the #[b HeroService] [injected](dependency-injection.html) into the `HeroService` constructor. +makeExample('server-communication/ts/app/toh/hero.service.ts', 'ctor') :marked - Look closely at how we call `#{_priv}http.get` + Look closely at how we call `!{_priv}http.get` +makeExample('server-communication/ts/app/toh/hero.service.ts', 'http-get', 'app/toh/hero.service.ts (getHeroes)')(format=".") :marked We pass the resource URL to `get` and it calls the server which should return heroes. @@ -195,7 +204,7 @@ h2#fetch-data Fetch data with the #[b HeroService] Alternatively, we can (temporarily) target a JSON file by changing the endpoint URL: +makeExample('server-communication/ts/app/toh/hero.service.ts', 'endpoint-json')(format=".") -block rxjs ++ifDocsFor('ts') :marked The return value may surprise us. @@ -253,7 +262,7 @@ l-main-section a#extract-data :marked ## Process the response object - Remember that our `getHeroes()` method mapped the `#{_priv}http.get` response object to heroes with an `#{_priv}extractData` helper method: + Remember that our `getHeroes()` method mapped the `!{_priv}http.get` response object to heroes with an `!{_priv}extractData` helper method: +makeExample('server-communication/ts/app/toh/hero.service.ts', 'extract-data', 'app/toh/hero.service.ts (excerpt)')(format=".") :marked The `response` object does not hold our data in a form we can use directly. @@ -274,7 +283,7 @@ block parse-json .l-sub-section :marked - We shouldn't expect the decoded JSON to be the heroes #{_array} directly. + We shouldn't expect the decoded JSON to be the heroes !{_array} directly. The server we're calling always wraps JSON results in an object with a `data` property. We have to unwrap it to get the heroes. This is conventional web api behavior, driven by @@ -296,7 +305,7 @@ block parse-json .callout.is-important header HTTP GET is delayed :marked - The `#{_priv}http.get` does **not send the request just yet!** This observable is + The `!{_priv}http.get` does **not send the request just yet!** This observable is [*cold*](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/gettingstarted/creating.md#cold-vs-hot-observables) which means the request won't go out until something *subscribes* to the observable. That *something* is the [HeroListComponent](#subscribe). @@ -328,7 +337,7 @@ a#hero-list-component h4 #[b HeroListComponent] error handling block hlc-error-handling :marked - Back in the `HeroListComponent`, where we called `#{_priv}heroService.getHeroes()`, + Back in the `HeroListComponent`, where we called `!{_priv}heroService.getHeroes()`, we supply the `subscribe` function with a second function parameter to handle the error message. It sets an `errorMessage` variable which we've bound conditionally in the `HeroListComponent` template. @@ -401,7 +410,7 @@ code-example(format="." language="javascript"). ### JSON results As with `getHeroes()`, we [extract the data](#extract-data) from the response using the - `#{_priv}extractData()` helper. + `!{_priv}extractData()` helper. block hero-list-comp-add-hero :marked @@ -409,7 +418,7 @@ block hero-list-comp-add-hero When the data, arrive it pushes the new hero object into its `heroes` array for presentation to the user. +makeExample('server-communication/ts/app/toh/hero-list.component.ts', 'addHero', 'app/toh/hero-list.component.ts (addHero)')(format=".") -block promises ++ifDocsFor('ts') h2#promises Fall back to Promises :marked Although the Angular `http` client API returns an `Observable` we can turn it into a @@ -490,7 +499,7 @@ figure.image-display block wikipedia-jsonp+ :marked Wikipedia offers a modern `CORS` API and a legacy `JSONP` search API. Let's use the latter for this example. - The Angular `Jsonp` service both extends the `#{_Http}` service for JSONP and restricts us to `GET` requests. + The Angular `Jsonp` service both extends the `!{_Http}` service for JSONP and restricts us to `GET` requests. All other HTTP methods throw an error because JSONP is a read-only facility. As always, we wrap our interaction with an Angular data access client service inside a dedicated service, here called `WikipediaService`. @@ -665,9 +674,9 @@ a#in-mem-web-api registered for module loading by SystemJS (see `systemjs.config.js`) :marked - The in-memory web API gets its data from #{_a_ca_class_with} a `createDb()` + The in-memory web API gets its data from !{_a_ca_class_with} a `createDb()` method that returns a map whose keys are collection names and whose values - are #{_array}s of objects in those collections. + are !{_array}s of objects in those collections. Here's the class we created for this sample based on the JSON data: +makeExample('server-communication/ts/app/hero-data.ts', null, 'app/hero-data.ts')(format=".") @@ -684,8 +693,10 @@ block redirect-to-web-api To enable our server simulation, we replace the default `XHRBackend` service with the in-memory web API service using standard Angular provider registration techniques. We initialize the in-memory web API with *seed data* from the mock hero dataset at the same time. +:marked + Here is the revised (and final) version of app/main.ts> demonstrating these steps. -p Here is the revised (and final) version of the #[code #[+adjExPath('app/main.ts')]] demonstrating these steps. -+makeExample('server-communication/ts/app/main.ts', 'final', 'app/main.ts (final)')(format=".") ++makeExcerpt('app/main.ts', 'final') -p See the full source code in the #[+liveExampleLink2()]. +:marked + See the full source code in the . diff --git a/public/docs/ts/latest/guide/structural-directives.jade b/public/docs/ts/latest/guide/structural-directives.jade index 54fb395ee6..cd832d83d1 100644 --- a/public/docs/ts/latest/guide/structural-directives.jade +++ b/public/docs/ts/latest/guide/structural-directives.jade @@ -15,7 +15,7 @@ block includes - [understand the asterisk (\*) in **ngFor*](#asterisk) - [write our own structural directive](#unless) -p Try the #[+liveExampleLink2()]. + Try the . .l-main-section diff --git a/public/docs/ts/latest/guide/template-syntax.jade b/public/docs/ts/latest/guide/template-syntax.jade index 42225b411d..317d6aa8b8 100644 --- a/public/docs/ts/latest/guide/template-syntax.jade +++ b/public/docs/ts/latest/guide/template-syntax.jade @@ -35,8 +35,7 @@ block includes * [pipe](#pipe) * [safe navigation operator (?.)](#safe-navigation-operator) -p. - The #[+liveExampleLink2()] + The demonstrates all of the syntax and code snippets described in this chapter. .l-main-section diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index 588be7896f..d137cd849f 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -18,23 +18,26 @@ block includes in #{_docsFor == 'ts' ? 'Dart' : 'TypeScript'} and JavaScript. Just select either of those languages from the combo-box in the banner. -h1 Try it! -p - | Try the #[+liveExampleLink2()] which loads the sample app - +ifDocsFor('ts') - |  in #[a(href="http://plnkr.co/" title="Plunker" target="_blank") plunker] - |  and displays the simple message: +:marked + # Try it! + + Try the which loads the sample app + + in plunker + + and displays the simple message: figure.image-display img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app") -h1 Build this app! :marked + # Build this app! + - [Prerequisite](#prereq): Install #{_prereq} - [Step 1](#create-and-configure): Create the app’s project folder and define package dependencies and special project setup - [Step 2](#root-component): Create the app’s Angular root component - - [Step 3](#main): Add `main.#{_docsFor}`, identifying the root component to Angular + - [Step 3](#main): Add main.ts, identifying the root component to Angular - [Step 4](#index): Add `index.html`, the web page that hosts the application - [Step 5](#build-and-run): Build and run the app - [Make some changes to the app](#make-some-changes) @@ -333,9 +336,9 @@ block create-main [SEO](http://www.google.com/webmasters/docs/search-engine-optimization-starter-guide.pdf). These targets require a different kind of bootstrap function that we'd import from a different library. - ### Why create separate *main.#{_docsFor}* and app component files? + ### Why create separate *main.ts* and app component files? - Both `main.#{_docsFor}` and the app component files are tiny. + Both main.ts and the app component files are tiny. This is just a QuickStart. We could have merged these two files into one and spared ourselves some complexity. @@ -462,7 +465,7 @@ h2#index Step 4: Add #[code index.html] a(id="my-app") :marked - When Angular calls the `bootstrap` function in `main.#{_docsFor}`, it reads the `AppComponent` + When Angular calls the `bootstrap` function in main.ts, it reads the `AppComponent` metadata, finds the `my-app` selector, locates an element tag named `my-app`, and renders our application's view between those tags. diff --git a/public/docs/ts/latest/tutorial/index.jade b/public/docs/ts/latest/tutorial/index.jade index d4a3110dcd..21f67233f7 100644 --- a/public/docs/ts/latest/tutorial/index.jade +++ b/public/docs/ts/latest/tutorial/index.jade @@ -24,10 +24,9 @@ include ../_util-fns Angular can do whatever we need it to do. We'll be covering a lot of ground at an introductory level but we’ll find plenty of links to chapters with greater depth. + + Run the . // #enddocregion intro - -p Run the #[+liveExampleLink2('', 'toh-6')]. - // #docregion main .l-main-section :marked diff --git a/public/docs/ts/latest/tutorial/toh-pt1.jade b/public/docs/ts/latest/tutorial/toh-pt1.jade index 3cbe3ab0f4..9ee468e456 100644 --- a/public/docs/ts/latest/tutorial/toh-pt1.jade +++ b/public/docs/ts/latest/tutorial/toh-pt1.jade @@ -5,8 +5,8 @@ include ../_util-fns Every story starts somewhere. Our story starts where the [QuickStart](../quickstart.html) ends. -p Run the #[+liveExampleLink2('', 'toh-1')] for this part. -:marked + Run the for this part. + Create a folder called `angular2-tour-of-heroes` and follow the [QuickStart](../quickstart.html) steps which provide the prerequisites, the folder structure, and the core files for our Tour of Heroes. @@ -170,8 +170,8 @@ code-example(language="html"). using the built-in `ngModel` directive. * The `ngModel` directive also propagates changes to every other binding of the `hero.name`. -p Run the #[+liveExampleLink2('', 'toh-1')] for this part. -:marked + Run the for this part. + Here's the complete `app.component.ts` as it stands now: +makeExample('toh-1/ts/app/app.component.ts', 'pt1', 'app.component.ts') diff --git a/public/docs/ts/latest/tutorial/toh-pt2.jade b/public/docs/ts/latest/tutorial/toh-pt2.jade index 86a5b73dd1..ce7c919672 100644 --- a/public/docs/ts/latest/tutorial/toh-pt2.jade +++ b/public/docs/ts/latest/tutorial/toh-pt2.jade @@ -6,8 +6,8 @@ include ../_util-fns We’ll expand our Tour of Heroes app to display a list of heroes, allow the user to select a hero, and display the hero’s details. -p Run the #[+liveExampleLink2('', 'toh-2')] for this part. -:marked + Run the for this part. + Let’s take stock of what we’ll need to display a list of heroes. First, we need a list of heroes. We want to display those heroes in the view’s template, so we’ll need a way to do that. @@ -300,8 +300,8 @@ code-example(language="bash"). * We added the ability to select a hero and show the hero’s details * We learned how to use the built-in directives `ngIf` and `ngFor` in a component’s template -p Run the #[+liveExampleLink2('', 'toh-2')] for this part. -:marked + Run the for this part. + ### The Road Ahead Our Tour of Heroes has grown, but it’s far from complete. We can't put the entire app into a single component. diff --git a/public/docs/ts/latest/tutorial/toh-pt3.jade b/public/docs/ts/latest/tutorial/toh-pt3.jade index 2b08697697..b45cd4980c 100644 --- a/public/docs/ts/latest/tutorial/toh-pt3.jade +++ b/public/docs/ts/latest/tutorial/toh-pt3.jade @@ -4,7 +4,7 @@ include ../_util-fns Our app is growing. Use cases are flowing in for reusing components, passing data to components, and creating more reusable assets. Let's separate the heroes list from the hero details and make the details component reusable. -p Run the #[+liveExampleLink2('', 'toh-3')] for this part. + Run the for this part. .l-main-section :marked @@ -243,7 +243,7 @@ code-example(format=".") * We learned to bind a parent component to a child component. * We learned to declare the application directives we need in a `directives` array. -p Run the #[+liveExampleLink2('', 'toh-3')] for this part. + Run the for this part. .l-main-section :marked diff --git a/public/docs/ts/latest/tutorial/toh-pt4.jade b/public/docs/ts/latest/tutorial/toh-pt4.jade index 16487a1cb7..12660bf643 100644 --- a/public/docs/ts/latest/tutorial/toh-pt4.jade +++ b/public/docs/ts/latest/tutorial/toh-pt4.jade @@ -15,7 +15,7 @@ include ../_util-fns Because data services are invariably asynchronous, we'll finish the chapter with a **!{_Promise}**-based version of the data service. -p Run the #[+liveExampleLink2('', 'toh-4')] for this part. + Run the for this part. .l-main-section :marked @@ -343,8 +343,8 @@ a#child-component * We created mock hero data and imported them into our service. * We designed our service to return a !{_Promise} and our component to get our data from the !{_Promise}. -p Run the #[+liveExampleLink2('', 'toh-4')] for this part. -:marked + Run the for this part. + ### The Road Ahead Our Tour of Heroes has become more reusable using shared components and services. We want to create a dashboard, add menu links that route between the views, and format data in a template. diff --git a/public/docs/ts/latest/tutorial/toh-pt5.jade b/public/docs/ts/latest/tutorial/toh-pt5.jade index 160672fb9a..d576064f2c 100644 --- a/public/docs/ts/latest/tutorial/toh-pt5.jade +++ b/public/docs/ts/latest/tutorial/toh-pt5.jade @@ -18,7 +18,8 @@ figure.image-display The [Routing and Navigation](../guide/router.html) chapter covers the router in more detail than we will in this tutorial. -p Run the #[+liveExampleLink2('', 'toh-5')] for this part. +:marked + Run the for this part. .l-sub-section img(src='/resources/images/devguide/plunker-separate-window-button.png' alt="pop out the window" align="right" style="margin-right:-20px") @@ -662,11 +663,10 @@ figure.image-display .l-main-section :marked ## Application structure and code -p. - Review the sample source code in the #[+liveExampleLink2('', 'toh-5')] for this chapter. + + Review the sample source code in the for this chapter. Verify that we have the following structure: -:marked .filetree .file angular2-tour-of-heroes .children diff --git a/public/docs/ts/latest/tutorial/toh-pt6.jade b/public/docs/ts/latest/tutorial/toh-pt6.jade index 4b25b30b86..5f65c5a421 100644 --- a/public/docs/ts/latest/tutorial/toh-pt6.jade +++ b/public/docs/ts/latest/tutorial/toh-pt6.jade @@ -17,7 +17,7 @@ block includes In this chapter we teach our application to make the corresponding HTTP calls to a remote server's web API. -p Run the #[+liveExampleLink2('', 'toh-6')] for this part. + Run the for this part. .l-main-section :marked @@ -57,7 +57,7 @@ block http-providers :marked We should be able to access `!{_Http}` services from anywhere in the application. - So we register them in the `bootstrap` call of `main.!{_docsFor}` where we + So we register them in the `bootstrap` call of main.ts where we launch the application and its root `AppComponent`. +makeExcerpt('app/main.ts','v1') @@ -361,8 +361,8 @@ block review .l-main-section :marked ## Application structure and code -p. - Review the sample source code in the #[+liveExampleLink2('', 'toh-6')] for this chapter. + + Review the sample source code in the for this chapter. Verify that we have the following structure: block filetree diff --git a/public/resources/js/directives/if-docs.js b/public/resources/js/directives/if-docs.js new file mode 100644 index 0000000000..d273053512 --- /dev/null +++ b/public/resources/js/directives/if-docs.js @@ -0,0 +1,25 @@ +/* +* Angular.io Example Conditional Directive +* +* Usage: +* ... +* +* This is equivalent to an ngIf that holds if this containing +* docs are for TypeScript. +*/ + +angularIO.directive('ifDocs', ['ngIfDirective', '$location', function (ngIfDirective, $location) { + var ngIf = ngIfDirective[0]; + + return { + transclude: ngIf.transclude, + priority: ngIf.priority, + terminal: ngIf.terminal, + restrict: ngIf.restrict, + link: function (scope, element, attrs) { + var ngIfCond = (attrs.ifDocs === 'dart') == !NgIoUtil.isDartDoc($location); + attrs.ngIf = function () { return !ngIfCond; } + ngIf.link.apply(ngIf, arguments); + } + }; +}]); \ No newline at end of file diff --git a/public/resources/js/directives/live-example.js b/public/resources/js/directives/live-example.js new file mode 100644 index 0000000000..bb7f9c404c --- /dev/null +++ b/public/resources/js/directives/live-example.js @@ -0,0 +1,54 @@ +/* +* Angular.io Live Example Directive +* +* Renders a link to a live/host example of the doc chapter +* app this directive is contained in. +* +* Usage: +* text +* Example: +*

    Run this chapter's example

    . +*/ + +angularIO.directive('liveExample', ['$location', function ($location) { + + function a(text, attrs) { + var attr = (attrs.href ? ' href="' + attrs.href + '"' : '') + + (attrs.target ? ' target="' + attrs.target + '"' : ''); + return '' + text + ''; + } + + function span(text) { return '' + text + ''; } + + return { + restrict: 'E', + + compile: function (tElement, attrs) { + var text = tElement.text() || 'live example'; + var ex = attrs.name || NgIoUtil.getExampleName($location); + var href, template; + + var isForDart = attrs.lang === 'dart' || NgIoUtil.isDartDoc($location); + var href = isForDart + ? 'http://angular-examples.github.io/' + ex + : '/resources/live-examples/' + ex + '/ts/plnkr.html'; + + // Link to live example. + var template = a(text, { href: href, target: '_blank' }); + + // The hosted example and sources are in different locations for Dart. + // Also show link to sources for Dart, unless noSource is specified. + if (isForDart && !attrs.hasOwnProperty('nosource')) { + var srcText = attrs.srcText || 'view source'; + var srcHref = 'http://github.com/angular-examples/' + ex; + template = span(template + ' (' + a(srcText, { href: srcHref, target: '_blank' }) + ')'); + } + + // UPDATE ELEMENT WITH NEW TEMPLATE + tElement.html(template); + + // RETURN ELEMENT + return function (scope, element, attrs) { }; + } + }; +}]); diff --git a/public/resources/js/directives/ngio-ex-path.js b/public/resources/js/directives/ngio-ex-path.js new file mode 100644 index 0000000000..72ee27309f --- /dev/null +++ b/public/resources/js/directives/ngio-ex-path.js @@ -0,0 +1,38 @@ +/* +* Angular.io Example File Path Directive +* +* Usage: +* some_path +* +* +* The latter gets treated as a block tag in markdown when at the start of a line. +* +* Yields +* some_path_possibly_adjusted +* +* The given path is assumed to be a TS app directory or +* source file path. When this directive is used in Dart docs +* it adjusts the path to conform to Dart directory and file +* name conventions. See NgIoUtil.adjustTsExamplePathForDart() +* for details. +*/ + +angularIO.directive('ngioEx', ['$location', function ($location) { + return { + restrict: 'AE', + + compile: function (tElement, attrs) { + var examplePath = attrs.path || tElement.text(); + if (NgIoUtil.isDartDoc($location) || attrs.lang === 'dart') { + examplePath = NgIoUtil.adjustTsExamplePathForDart(examplePath); + } + var template = '' + examplePath + ''; + + // UPDATE ELEMENT WITH NEW TEMPLATE + tElement.html(template); + + // RETURN ELEMENT + return function (scope, element, attrs) { }; + } + }; +}]); diff --git a/public/resources/js/util.js b/public/resources/js/util.js new file mode 100644 index 0000000000..2582df3f27 --- /dev/null +++ b/public/resources/js/util.js @@ -0,0 +1,87 @@ +// This will be nicer once we switch to Ng2. For now, define a singleton. + +var NgIoUtil = (function () { + + function NgIoUtil() { } + + NgIoUtil.isDartDoc = function ($location) { + var loc = $location.absUrl(); + return loc.includes('/docs/dart/'); + }; + + // The following util functions are adapted from _utils-fn.jade. + // Note that basename(), etc doesn't quite follow + // https://nodejs.org/api/path.html + // but it suits our purpose for now. + + NgIoUtil.adjustTsExamplePathForDart = function (_path) { + /* Convert a TS example path into a Dart example path. E.g., + * + * - app/main.ts -> web/main.dart + * - displaying-data/ts/app/app.component.2.ts -> displaying-data/dart/lib/app_component.dart + * + * Notice that the '.2' is dropped from the name. + */ + if (!_path) return _path; + var path = _path.trim(); + var folder = NgIoUtil.folderName(path); + var ext = NgIoUtil.extname(path); + var baseNameNoExt = NgIoUtil.basename(path, ext); + var inWebFolder = baseNameNoExt.match(/^(main|index)(\.\d)?$/); + + // Adjust the folder path, e.g., '/ts/' -> '/dart/' + folder = folder + .replace(/(^|\/)ts($|\/)/, '$1dart$2') + .replace(/(^|\/)app($|\/)/, inWebFolder ? '$1web$2' : '$1lib$2'); + + // Special case not handled above: e.g., index.html -> web/index.html + if (baseNameNoExt.match(/^(index|styles)(\.\d)?$/) && !folder.match(/web$/)) + folder = (folder ? folder + '/' : '') + 'web'; + + // In file name, replace special characters with underscore + baseNameNoExt = baseNameNoExt.replace(/[\-\.]/g, '_'); + + // Adjust the file extension + if (ext == '.ts') ext = '.dart'; + return (folder ? folder + '/' : '') + baseNameNoExt + ext; + }; + + NgIoUtil.extname = function (path) { + var i = path.lastIndexOf('.'); + return i > 0 ? path.substr(i) : ''; + }; + + NgIoUtil.basename = function (path, optExt) { + var i = path.lastIndexOf('/'); + var name = i > 0 ? path.substr(i + 1) : path; + if (optExt) name = name.substr(0, name.length - optExt.length); + return name; + }; + + NgIoUtil.folderName = function (path) { + var i = path.lastIndexOf('/'); + return i > 0 ? path.substr(0, i) : ''; + }; + + NgIoUtil._exampleName = ''; // example name is unique to a page; e.g., toh-1 + + NgIoUtil.setExampleName = function (name) { + // Adjust name for known cases where chapter name is not the example name. + var matches = name.match(/(toh-)pt(\d+)/); + if (matches) name = matches[1] + matches[2]; + NgIoUtil._exampleName = name; + } + + NgIoUtil.getExampleName = function ($location) { + if (!NgIoUtil._exampleName) { + // TODO: use $location.path() instead(?). It seems to be empty. + var loc = $location.absUrl(); + // E.g., https://example.com/docs/dart/latest/guide/displaying-data.html + var matches = loc.match(/.*\/([\w\.\-]+)\.html/); + if (matches) NgIoUtil.setExampleName(matches[1]); // cache name + } + return NgIoUtil._exampleName; + }; + + return NgIoUtil; +} ()); From 266400b44bac980331c4a0bccb6be2dbde95e7be Mon Sep 17 00:00:00 2001 From: Foxandxss Date: Mon, 4 Jul 2016 15:54:11 +0200 Subject: [PATCH 6/7] chore: update README with latest additions closes #1820 --- .travis.yml | 4 ++-- README.md | 13 +++++++++++-- {script => scripts}/install.sh | 0 3 files changed, 13 insertions(+), 4 deletions(-) rename {script => scripts}/install.sh (100%) diff --git a/.travis.yml b/.travis.yml index f5624c7eb9..b0f7d92a6a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,13 +17,13 @@ env: matrix: fast_finish: true allow_failures: - - env: "SCRIPT=\"run-e2e-tests --fast\" PREVIEW=true" + - env: "SCRIPT=\"run-e2e-tests --fast\" PREVIEW=true" before_install: - npm install -g gulp --no-optional before_script: - sh -e /etc/init.d/xvfb start install: - - ./script/install.sh + - ./scripts/install.sh - if [[ $PREVIEW == true ]]; then npm install --prefix public/docs/_examples angular/{core,common,compiler,platform-browser,platform-browser-dynamic,http,forms,router-deprecated,router,upgrade}-builds; fi script: - gulp $SCRIPT diff --git a/README.md b/README.md index 336a589c4a..1e0d3095f5 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ This site relies heavily on node and npm. 1. Make sure you are using the latest node and npm; if not install [nvm](https://github.com/creationix/nvm) to get node going on your machine. -1. install these npm packages *globally*: `npm install -g harp gulp protractor` +1. install these npm packages *globally*: `npm install -g harp gulp` 1. clone this repo and the [angular source code repo](https://github.com/angular/angular) to the same parent directory. The two cloned repo directories must be sibling. @@ -98,7 +98,7 @@ Look at the scripts in `package.json` for other options. Also, open any `plunkr.no-link.html` to see the code execute in plunker (you may have to run `gulp build-plunkers` first to create/update). -You may want to check that your example is free of lint errors. +You must check that your example is free of lint errors. - `gulp lint` ### Sample end-to-end tests @@ -112,6 +112,15 @@ All samples should be covered to some degree by end-to-end tests: Any combination of options is possible. +### Resetting the project +This project generates a lot of untracked files, if you wish to reset it to a mint state, you can run: + +- `git clean -xdf` + +Also, there is a script available for Linux and OSX users that will setup the project using the steps shown in this section: + +- `./scripts/install.sh` + ## Technology Used - Angular 1.x: The production ready version of Angular diff --git a/script/install.sh b/scripts/install.sh similarity index 100% rename from script/install.sh rename to scripts/install.sh From 37b377ddb3cf44cd4a44e778ab39157a7ff81b48 Mon Sep 17 00:00:00 2001 From: Foxandxss Date: Mon, 4 Jul 2016 15:59:13 +0200 Subject: [PATCH 7/7] docs: update node and npm version recommendations closes #1821 --- public/docs/ts/latest/cli-quickstart.jade | 2 +- public/docs/ts/latest/guide/npm-packages.jade | 2 +- public/docs/ts/latest/quickstart.jade | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/public/docs/ts/latest/cli-quickstart.jade b/public/docs/ts/latest/cli-quickstart.jade index 0a9a2d8636..d66c8895e4 100644 --- a/public/docs/ts/latest/cli-quickstart.jade +++ b/public/docs/ts/latest/cli-quickstart.jade @@ -33,7 +33,7 @@ h2#devenv Step 1. Set up the Development Environment if they are not already on your machine. .l-sub-section :marked - **Verify that you are running node `v5.x.x` and npm `3.x.x`** + **Verify that you are running node `v4.x.x` and npm `3.x.x`** by running `node -v` and `npm -v` in a terminal/console window. Older versions produce errors. :marked diff --git a/public/docs/ts/latest/guide/npm-packages.jade b/public/docs/ts/latest/guide/npm-packages.jade index 5a3268b6a2..4981177dba 100644 --- a/public/docs/ts/latest/guide/npm-packages.jade +++ b/public/docs/ts/latest/guide/npm-packages.jade @@ -10,7 +10,7 @@ include ../_util-fns Get it now if it's not already installed on your machine - **Verify that you are running at least node `v5.x.x` and npm `3.x.x`** + **Verify that you are running at least node `v4.x.x` and npm `3.x.x`** by running `node -v` and `npm -v` in a terminal/console window. Older versions produce errors. diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index d137cd849f..5de3efe99c 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -52,7 +52,7 @@ block setup-tooling if they are not already on your machine. .l-sub-section :marked - **Verify that you are running at least node `v5.x.x` and npm `3.x.x`** + **Verify that you are running at least node `v4.x.x` and npm `3.x.x`** by running `node -v` and `npm -v` in a terminal/console window. Older versions produce errors.