From 6d2d52c588bd66ee8deceafb5ffa2457e4d357e0 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 20 May 2016 16:18:58 -0700 Subject: [PATCH] docs(dart): cleanup 'live example' links (#1449) This fixes various issues such as: - missing space in Dart version between the live demo and demo source links. - Live example link directing to Plunker for Dart. The main mixins (`liveExampleLink`*) used to support the generation of links now assume reasonable default values for their arguments, and in most cases the defaults are used. * Dart example links: use http vs https As agree to with @kwalrath. --- public/docs/dart/latest/_util-fns.jade | 12 ++++++--- public/docs/ts/latest/_util-fns.jade | 9 ++++--- .../ts/latest/guide/attribute-directives.jade | 5 ++-- .../ts/latest/guide/component-styles.jade | 5 ++-- .../hierarchical-dependency-injection.jade | 4 +-- .../docs/ts/latest/guide/lifecycle-hooks.jade | 4 +-- public/docs/ts/latest/guide/pipes.jade | 26 +++++++++---------- .../ts/latest/guide/server-communication.jade | 6 ++--- .../latest/guide/structural-directives.jade | 4 +-- public/docs/ts/latest/quickstart.jade | 2 +- 10 files changed, 42 insertions(+), 35 deletions(-) diff --git a/public/docs/dart/latest/_util-fns.jade b/public/docs/dart/latest/_util-fns.jade index 380b4ac7a1..98be78138f 100644 --- a/public/docs/dart/latest/_util-fns.jade +++ b/public/docs/dart/latest/_util-fns.jade @@ -14,12 +14,16 @@ include ../../../_includes/_util-fns - var _liveLink = 'sample repo'; mixin liveExampleLink(linkText, exampleUrlPartName) - a(href='https://angular-examples.github.io/#{exampleUrlPartName}' target="_blank")= linkText + - var text = linkText || 'live example'; + - var ex = exampleUrlPartName || getExampleName(); + - var href = 'http://angular-examples.github.io/' + ex; + a(href='#{href}' target="_blank")= text mixin liveExampleLink2(linkText, exampleUrlPartName) - - var liveExampleSourceLinkText = attributes.srcLinkText || 'view source' - | #[+liveExampleLink(linkText, exampleUrlPartName)] - | (#[a(href='https://github.com/angular-examples/#{exampleUrlPartName}' target="_blank") #{liveExampleSourceLinkText}]) + - var srcText = attributes.srcText || 'view source'; + - var ex = exampleUrlPartName || attributes.example || getExampleName(); + - var href = 'http://github.com/angular-examples/' + ex; + span #[+liveExampleLink(linkText, ex)] (#[a(href='#{href}' target="_blank") #{srcText}]) - var adjustExamplePath = function(_path) { - if(!_path) return _path; diff --git a/public/docs/ts/latest/_util-fns.jade b/public/docs/ts/latest/_util-fns.jade index 5c3d720cf3..e31e48af09 100644 --- a/public/docs/ts/latest/_util-fns.jade +++ b/public/docs/ts/latest/_util-fns.jade @@ -5,8 +5,11 @@ include ../../../_includes/_util-fns //- Other values match the defaults. mixin liveExampleLink(linkText, exampleUrlPartName) - a(href='/resources/live-examples/#{exampleUrlPartName}/ts/plnkr.html' target="_blank")= linkText + - var text = linkText || 'live example'; + - var ex = exampleUrlPartName || getExampleName(); + - var href = '/resources/live-examples/' + ex + '/ts/plnkr.html'; + a(href='#{href}' target="_blank")= text mixin liveExampleLink2(linkText, exampleUrlPartName) - //- In Dart this also gives a link to the source. - | #[+liveExampleLink(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 b175139fd0..4540f844ac 100644 --- a/public/docs/ts/latest/guide/attribute-directives.jade +++ b/public/docs/ts/latest/guide/attribute-directives.jade @@ -10,8 +10,9 @@ block includes * [apply the attribute directive to an element in a template](#apply-directive) * [respond to user-initiated events](#respond-to-user) * [pass values into the directive using data binding](#bindings) -p. - #[+liveExampleLink2('Live example', 'attribute-directives')]. + +p Try the #[+liveExampleLink2()]. + :marked ## Directives overview diff --git a/public/docs/ts/latest/guide/component-styles.jade b/public/docs/ts/latest/guide/component-styles.jade index 3b58a1ec86..d7975713a6 100644 --- a/public/docs/ts/latest/guide/component-styles.jade +++ b/public/docs/ts/latest/guide/component-styles.jade @@ -19,9 +19,8 @@ block includes * [Controlling View Encapsulation: Emulated, Native, and None](#view-encapsulation) * [Appendix 1: Inspecting the generated runtime component styles](#inspect-generated-css) * [Appendix 2: Loading Styles with Relative URLs](#relative-urls) -p - | #[+liveExampleLink2('Run the live example', 'component-styles')]  - | of the code shown in this chapter. + +p Run the #[+liveExampleLink2()] of the code shown in this chapter. .l-main-section :marked diff --git a/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade b/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade index 72f6b2bf74..050a0d69c6 100644 --- a/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade +++ b/public/docs/ts/latest/guide/hierarchical-dependency-injection.jade @@ -12,8 +12,8 @@ block includes interesting and useful results. In this chapter we explore these points and write some code. -p - | Try the #[+liveExampleLink2('live example', 'hierarchical-dependency-injection')]. + +p Try the #[+liveExampleLink2()]. .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 903160ca97..f29ffc40d2 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('live example', 'lifecycle-hooks')]. +p Try the #[+liveExampleLink2()]. a#hooks-overview .l-main-section @@ -199,7 +199,7 @@ a#the-sample .l-main-section h2 Lifecycle exercises p. - The #[+liveExampleLink('live example', 'lifecycle-hooks')] + The #[+liveExampleLink()] demonstrates the lifecycle hooks in action through a series of exercises presented as components under the control of the root `AppComponent`. :marked diff --git a/public/docs/ts/latest/guide/pipes.jade b/public/docs/ts/latest/guide/pipes.jade index 4fa76296bc..1f453d0a29 100644 --- a/public/docs/ts/latest/guide/pipes.jade +++ b/public/docs/ts/latest/guide/pipes.jade @@ -17,7 +17,7 @@ block includes In fact, we'd like to apply them in our HTML templates as we do styles. p. Welcome, Angular pipes, the simple display-value transformations that we can declare in our HTML! - Try the #[+liveExampleLink2('live example', 'pipes')]. + Try the #[+liveExampleLink2()]. .l-main-section :marked @@ -169,7 +169,7 @@ figure.image-display Custom pipes must be registered manually. p. - If we try the #[+liveExampleLink('live code', 'pipes')] example, + If we try the #[+liveExampleLink()], we can probe its behavior by changing the value and the optional exponent in the template. :marked @@ -219,10 +219,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='.') -:marked - When we run the sample now we see odd behavior (try it in the [live example](/resources/live-examples/pipes/ts/plnkr.html)). +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 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. @@ -238,7 +238,7 @@ a#change-detection *If we **mutate** the #{_array}, no pipe is invoked and no display updated; if we **replace** the #{_array}, then the pipe executes and the display is updated*. - The *Flying Heroes* in the [live example](/resources/live-examples/pipes/ts/plnkr.html) extends the + The *Flying Heroes* extends the code with checkbox switches and additional displays to help us experience these effects. figure.image-display @@ -328,15 +328,15 @@ 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='.') -:marked +p. The only substantive change is the pipe. - We can confirm in the [live example](/resources/live-examples/pipes/ts/plnkr.html) - that the *flying heroes* display updates as we enter new heroes even when we mutate the `heroes` #{_array}. -- var _dollar = _docsFor === 'ts' ? '$' : ''; -:marked - - ### The impure *AsyncPipe* + 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}. +- var _dollar = _docsFor === 'ts' ? '$' : ''; +h3#async-pipe The impure #[i AsyncPipe] +:marked The Angular `AsyncPipe` is an interesting example of an impure pipe. The `AsyncPipe` accepts a `#{_Promise}` or `#{_Observable}` as input and subscribes to the input automatically, eventually returning the emitted value(s). diff --git a/public/docs/ts/latest/guide/server-communication.jade b/public/docs/ts/latest/guide/server-communication.jade index eea4772a11..b41274113c 100644 --- a/public/docs/ts/latest/guide/server-communication.jade +++ b/public/docs/ts/latest/guide/server-communication.jade @@ -36,9 +36,9 @@ 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. +p. We illustrate these topics with code that you can - #[+liveExampleLink2('run live in a browser', 'server-communication')]. + #[+liveExampleLink2('run live in a browser')]. .l-main-section h1 Demos @@ -694,4 +694,4 @@ block redirect-to-web-api 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=".") -p See the full source code in the #[+liveExampleLink2('live example', 'server-communication')]. +p See the full source code in the #[+liveExampleLink2()]. diff --git a/public/docs/ts/latest/guide/structural-directives.jade b/public/docs/ts/latest/guide/structural-directives.jade index c69cc870c0..54fb395ee6 100644 --- a/public/docs/ts/latest/guide/structural-directives.jade +++ b/public/docs/ts/latest/guide/structural-directives.jade @@ -14,8 +14,8 @@ block includes - [discover the <template> element](#template) - [understand the asterisk (\*) in **ngFor*](#asterisk) - [write our own structural directive](#unless) -p - | Try the #[+liveExampleLink2('live example', 'structural-directives')]. + +p Try the #[+liveExampleLink2()]. .l-main-section diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index eb47c58e04..782e3d4713 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -22,7 +22,7 @@ block includes h1 Try it! p - | Try the #[+liveExampleLink2('live example', 'quickstart')] which loads the sample app + | 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: