diff --git a/public/_includes/_util-fns.jade b/public/_includes/_util-fns.jade index 592068484d..550330210c 100644 --- a/public/_includes/_util-fns.jade +++ b/public/_includes/_util-fns.jade @@ -2,7 +2,7 @@ //- _docsFor: used to identify the language this version of the docs if for; //- Should be one of: 'ts', 'dart' or 'js'. Set in lang specific _util-fns file. -- var _docsFor = ''; +- var _docsFor = ''; //- Should match `_docsFor`, but in this case provides the full capitalized //- name of the language. @@ -29,6 +29,10 @@ - var _Promise = 'Promise'; - var _Observable = 'Observable'; +//- Location of sample code +- var _liveLink = 'live link'; + + //- Used to prefix identifiers that are private. In Dart this will be '_'. - var _priv = ''; @@ -46,7 +50,7 @@ mixin adjExPath(path) | #{adjustExamplePath(path)} else | #{path} - + mixin includeShared(filePath, region) - var newPath = translatePath(filePath, region); !=partial(newPath) @@ -69,8 +73,8 @@ mixin makeExample(_filePath, region, _title, stylePatterns) code-example(language="#{language}" format="#{format}") != styleString(frag, stylePatterns) -//- Like makeExample, but the first argument is a path that is -//- relative to the project root. Unless title is defined, +//- Like makeExample, but the first argument is a path that is +//- relative to the project root. Unless title is defined, //- the project relative path will be used. mixin makeProjExample(projRootRelativePath, region, title, stylePatterns) - var relPath = projRootRelativePath.trim(); @@ -83,7 +87,7 @@ mixin makeProjExample(projRootRelativePath, region, title, stylePatterns) +makeExample(filePath, region, title, stylePatterns) //- Like makeExample, but doesn't show line numbers, and the first -//- argument is a path that is relative to the example project root. +//- argument is a path that is relative to the example project root. //- Unless title is defined, the project relative path will be used. //- Title will always end with a phrase in parentheses; if no such //- ending is given, then the title will be suffixed with @@ -164,7 +168,7 @@ script. el.style.display = isVerbose ? 'block' : 'none'; var el = document.querySelector('button.verbose.on'); el.style.display = isVerbose ? 'none' : 'block'; - + CCSStylesheetRuleStyle('main','.l-verbose-section', 'display', isVerbose ? 'block' : 'none'); } diff --git a/public/docs/dart/latest/_util-fns.jade b/public/docs/dart/latest/_util-fns.jade index 3f38aa8bea..380b4ac7a1 100644 --- a/public/docs/dart/latest/_util-fns.jade +++ b/public/docs/dart/latest/_util-fns.jade @@ -11,13 +11,14 @@ include ../../../_includes/_util-fns - var _Lang = 'Dart'; - var _Promise = 'Future'; - var _Observable = 'Stream'; +- var _liveLink = 'sample repo'; mixin liveExampleLink(linkText, exampleUrlPartName) a(href='https://angular-examples.github.io/#{exampleUrlPartName}' target="_blank")= linkText mixin liveExampleLink2(linkText, exampleUrlPartName) - var liveExampleSourceLinkText = attributes.srcLinkText || 'view source' - | #[+liveExampleLink(linkText, exampleUrlPartName)] + | #[+liveExampleLink(linkText, exampleUrlPartName)] | (#[a(href='https://github.com/angular-examples/#{exampleUrlPartName}' target="_blank") #{liveExampleSourceLinkText}]) - var adjustExamplePath = function(_path) { @@ -29,7 +30,7 @@ mixin liveExampleLink2(linkText, exampleUrlPartName) - var baseName = getBaseFileName(path) || path; // TODO: have getBaseFileName() return path - var baseNameNoExt = baseName.substr(0,baseName.length - (extn.length + 1)); - var inWebFolder = baseNameNoExt.match(/^(main|index(\.\d)?)$/); -- // Adjust the folder path, e.g., ts -> dart +- // 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 = (folder ? folder + '/' : '') + 'web'; diff --git a/public/docs/dart/latest/guide/index.jade b/public/docs/dart/latest/guide/index.jade index 8ef237ed68..417bf9ea8d 100644 --- a/public/docs/dart/latest/guide/index.jade +++ b/public/docs/dart/latest/guide/index.jade @@ -1,93 +1,13 @@ -include ../_util-fns +extends ../../../ts/latest/guide/index.jade -:marked - This Developers Guide is a practical guide to Angular for experienced programmers who - are building client applications in HTML and Dart. -figure - img(src="/resources/images/devguide/intro/people.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:10px" ) -:marked - We are on a journey together to understand how Angular works and, more importantly, - how to make it work for us. We look at our application requirements and we see problems to solve. -
+block includes + include ../_util-fns - * How do we get data onto the screen and handle user interactions? - * How do we organize our code into manageable, cohesive chunks of functionality that work together? - * What are the essential Angular building blocks and how do they help? - * How do we minimize routine, mechanical coding in favor of declarative, higher level constructs without losing control? - - This chapter begins the journey. - - -:marked - # How to read this guide - Each chapter of this guide targets an Angular feature, - showing how to use it to solve a programming problem. - - All the chapters include code snippets ... snippets we can reuse in our own applications. - Typically, these snippets are excerpts from a sample application that accompanies the chapter. - - **All the source files** for each sample app are displayed together at the **end of each chapter.** - - - - - - - - Here is a learning path we might follow: - - 1. First, be familiar with Dart programming and with web concepts such as - the DOM, HTML, and CSS. Dart tutorials such as - [Get Started](https://www.dartlang.org/docs/tutorials/get-started/) and - [Connect Dart & HTML](https://www.dartlang.org/docs/tutorials/connect-dart-html/) - are a great way to start. - - 1. Follow the [QuickStart](../quickstart.html), which is the "Hello, World" of Angular 2. - It shows how to set up the libraries and tools needed to write *any* Angular app. - It ends with a "proof of life", a running Angular app. - - 1. Next, read the Developers Guide chapters in order: - - 1. The rest of this chapter, especially the Architecture overview - 1. [Displaying Data](displaying-data.html) - 1. [User Input](user-input.html) - 1. [Forms](forms.html) - - - - 1. Consider hopping over to the [TypeScript docs](/docs/ts/latest/) - since they're currently ahead of the Dart docs. (We're working on that!) - Especially check out the [Tutorial](/docs/ts/latest/tutorial/) and - [Cheat Sheet](/docs/ts/latest/guide/cheatsheet.html), and the guide chapters - [Dependency Injection](/docs/ts/latest/guide/dependency-injection.html) - and [Template Syntax](/docs/ts/latest/guide/template-syntax.html). - - - - Don't miss the [Cheat Sheet](cheatsheet.html), a handy map to Angular. - - -.l-main-section -:marked - # Appendix: The Hero Staffing Agency - - There's a backstory to the samples in this guide. - - The world is full of crises large and small. - Fortunately, courageous heroes are prepared to take on every challenge. - The shadowy Hero Staffing Agency matches crises to heroes. - - We are contract developers, hired by the Agency to build an application to manage their operations. - The Agency maintains a stable of heroes with special powers. - Ordinary humans submit crises as job requests. The heroes bid to take the job, and the Agency - assigns each job accordingly. - - Our application handles every detail of recruiting, tracking, and job assignment. - For example, the [Forms](forms.html) chapter features a screen for - entering personal information about heroes: - -figure.image-display - img(src="/resources/images/devguide/forms/hero-form-1.png" width="400px" alt="Clean Form") +block example-links + :marked + Look for a link to that sample near the top of each page. + For example, the sample repo https://github.com/angular-examples/architecture + contains the code + for the [Architecture](architecture.html) chapter's sample. + A running version of that sample is at + https://angular-examples.github.io/architecture/. diff --git a/public/docs/ts/latest/guide/index.jade b/public/docs/ts/latest/guide/index.jade index a6728b3a79..9fc8f82f68 100644 --- a/public/docs/ts/latest/guide/index.jade +++ b/public/docs/ts/latest/guide/index.jade @@ -1,4 +1,5 @@ -include ../_util-fns +block includes + include ../_util-fns // #docregion intro - var langName = current.path[1] == 'ts' ? 'TypeScript' : 'JavaScript' @@ -17,7 +18,7 @@ figure :marked # Organization - + The documentation is divided into major thematic sections, each a collection of chapters devoted to that theme. // #enddocregion how-to-read-1 @@ -26,14 +27,16 @@ figure table(width="100%") col(width="15%") col + tr(style=top) + td QuickStart + td + :marked + The foundation for every chapter and sample in this documentation. tr(style=top) td Tutorial td :marked - A step-by-step, immersive approach to learning Angular. - It begins with the [QuickStart](../quickstart.html), - the foundation for every chapter and sample in this documentation, - followed by the [*Tour of Heroes* tutorial](../tutorial) that + A step-by-step, immersive approach to learning Angular that introduces the major features of Angular in an application context. tr(style=top) td Basics @@ -44,86 +47,83 @@ table(width="100%") td Developer Guide td :marked - In depth analysis of Angular features and development practices. + In-depth analysis of Angular features and development practices. tr(style=top) td Cookbook td :marked Recipes for specific application challenges, mostly code snippets with a minimum of exposition. tr(style=top) - td Reference + td API Reference td :marked - Angular-specific reference material, most notably the [API Guide](../api) - with its authoritative details about each member in the Angular libraries. - tr(style=top) - td Resources - td - :marked - Other places to go for help and information. + Authoritative details about each member of the Angular libraries. :marked - # Learning Path - We don't have to read the guide straight through. Most chapters stand on their own. - - We recommend a learning path for those new to Angular. + # Learning path + We don't have to read the guide straight through. Most chapters stand on their own. + + We recommend a learning path for those new to Angular. Most of that path runs through the *Basics* section: - 1. Read the [Architecture Overview](architecture.html) to get the big picture. - - 1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2. - It shows us how to setup the libraries and tools we'll need to write *any* Angular app. - - 1. Take the *Tour of Heroes* [Tutorial](../tutorial) which picks up from where the QuickStart leaves off - and builds a simple data-driven app. + 1. Read the [Architecture](architecture.html) overview to get the big picture. + + 1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2. + It shows us how to set up the libraries and tools we'll need to write *any* Angular app. + + 1. Take the *Tour of Heroes* [Tutorial](../tutorial), which picks up from where the QuickStart leaves off + and builds a simple data-driven app. Simple, yes, but with the essential characteristics we'd expect of a professional application: - a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access. - + a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access. + Return to the *Basics* section and continue in the suggested order: - + 1. [Displaying Data](displaying-data.html) explains how to get information on to the screen. - + 1. [User Input](user-input.html) covers the basics of responding to user behavior. - + 1. [Forms](forms.html) handle user data entry and validation within the UI. - + 1. [Dependency Injection](dependency-injection.html) is the way we build large, maintainable applications - from small, single purpose parts. - - 1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML. + from small, single-purpose parts. + + 1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML. With this foundation, we can read and understand any chapter in the guide. // #enddocregion how-to-read-2 // #docregion the-rest :marked - # Code Samples - - Every chapter includes code snippets that we can reuse in our own applications. + # Code samples + + Every chapter includes code snippets that we can reuse in our own applications. These snippets are excerpts from a sample application that accompanies the chapter. - - Look for a link to a running version of that sample near the top of each page - such as this [live example](/resources/live-examples/architecture/ts/plnkr.html) from the [Architecture](architecture.html) chapter. - - The link launches a browser-based code editor where we can inspect, modify, save, and download the code. - - A few early chapters are written as tutorials and are clearly marked as such. - Most chapters are *not* tutorials. + +block example-links + :marked + Look for a link to a running version of that sample near the top of each page, + such as this [live example](/resources/live-examples/architecture/ts/plnkr.html) from the [Architecture](architecture.html) chapter. + + The link launches a browser-based code editor where we can inspect, modify, save, and download the code. + +:marked + A few early chapters are written as tutorials and are clearly marked as such. + Most chapters are *not* tutorials. They highlight key points in code rather than explain each step necessary to build the sample. - We can always get the full source by way of the live link. - - ## References - + We can always get the full source by way of the #{_liveLink}. + + # Reference pages + The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios. - + The [Glossary](glossary.html) defines terms that Angular developers should know. - - The [API Guide](../api/) is the authority on every public-facing member of the Angular libraries. - + + The [API Reference](../api/) is the authority on every public-facing member of the Angular libraries. + # Feedback - + We welcome feedback! Leave a comment by clicking the icon in upper right corner of the banner. - - Post *documentation* issues and pull requests on the + + Post *documentation* issues and pull requests on the [angular.io](https://github.com/angular/angular.io) github repository. - + Post issues with *Angular 2 itself* to the [angular](https://github.com/angular/angular) github repository. // #enddocregion the-rest