Skip to content
This repository has been archived by the owner on Apr 12, 2024. It is now read-only.

Commit

Permalink
docs(*): fix headings, links, and wordings
Browse files Browse the repository at this point in the history
  • Loading branch information
Narretz committed Jan 25, 2018
1 parent 09f1325 commit 0016265
Show file tree
Hide file tree
Showing 4 changed files with 50 additions and 50 deletions.
54 changes: 27 additions & 27 deletions docs/content/guide/component-router.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ The result is that we end up with a hierarchy of **Routing Components** rendered
![Component Hierarchy](img/guide/component-hierarchy.svg)


# Example Heroes App
## Example Heroes App

You can see the complete application running below.

Expand Down Expand Up @@ -459,12 +459,12 @@ You can see the complete application running below.
</example>


# Getting Started
### Getting Started

In the following sections we will step through building this application. The finished application has views
to display list and detail views of Heroes and Crises.

## Install the libraries
#### Install the libraries

It is easier to use [Yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com) to install the
**Component Router** module. For this guide we will also install AngularJS itself via Yarn:
Expand All @@ -475,7 +475,7 @@ yarn add angular@1.5.x @angular/router@0.2.0
```


## Load the scripts
#### Load the scripts

Just like any Angular application, we load the JavaScript files into our `index.html`:

Expand All @@ -494,7 +494,7 @@ You also need to include ES6 shims for browsers that do not support ES6 code (In
<script src="https://unpkg.com/angular2/es6/dev/src/testing/shims_for_IE.js"></script>
```

## Create the `app` module
#### Create the `app` module

In the app.js file, create the main application module `app` which depends on the `ngComponentRouter`
module, which is provided by the **Component Router** script.
Expand Down Expand Up @@ -547,7 +547,7 @@ must have a base URL.
...
```

## Bootstrap AngularJS
#### Bootstrap AngularJS

Bootstrap the Angular application and add the top level App Component.

Expand All @@ -559,7 +559,7 @@ Bootstrap the Angular application and add the top level App Component.
```


# Implementing the AppComponent
### Implementing the AppComponent

In the previous section we have created a single top level **App Component**. Let's now create some more
**Routing Components** and wire up **Route Config** for those. We start with a Heroes Feature, which
Expand All @@ -577,7 +577,7 @@ We are going to have a `Heroes` Component for the Heroes feature of our applicat
and `HeroDetail` **Components** that will actually display the two different views.


## App Component
#### App Component

Configure the **App Component** with a template and **Route Config**:

Expand All @@ -598,7 +598,7 @@ Configure the **App Component** with a template and **Route Config**:
The **App Component** has an `<ng-outlet>` directive in its template. This is where the child **Components**
of this view will be rendered.

### ngLink
#### ngLink

We have used the `ng-link` directive to create a link to navigate to the Heroes Component. By using this
directive we don't need to know what the actual URL will be. We can let the Router generate that for us.
Expand All @@ -607,7 +607,7 @@ We have included a link to the Crisis Center but have not included the `ng-link`
implemented the CrisisCenter component.


### Non-terminal Routes
#### Non-terminal Routes

We need to tell the **Router** that the `Heroes` **Route Definition** is **non-terminal**, that it should
continue to match **Routes** in its child **Components**. We do this by adding a **continuation ellipsis
Expand All @@ -616,14 +616,14 @@ Without the **continuation ellipsis** the `HeroList` **Route** will never be mat
stop at the `Heroes` **Routing Component** and not try to match the rest of the URL.


## Heroes Feature
### Heroes Feature

Now we can implement our Heroes Feature which consists of three **Components**: `Heroes`, `HeroList` and
`HeroDetail`. The `Heroes` **Routing Component** simply provides a template containing the {@link ngOutlet}
directive and a **Route Config** that defines a set of child **Routes** which delegate through to the
`HeroList` and `HeroDetail` **Components**.

## HeroesComponent
### HeroesComponent

Create a new file `heroes.js`, which defines a new Angular module for the **Components** of this feature
and registers the Heroes **Component**.
Expand Down Expand Up @@ -651,20 +651,20 @@ and also to add the module as a dependency of the `app` module:
angular.module('app', ['ngComponentRouter', 'heroes'])
```

### Use As Default
#### Use As Default
The `useAsDefault` property on the `HeroList` **Route Definition**, indicates that if no other **Route
Definition** matches the URL, then this **Route Definition** should be used by default.

### Route Parameters
#### Route Parameters
The `HeroDetail` Route has a named parameter (`id`), indicated by prefixing the URL segment with a colon,
as part of its `path` property. The **Router** will match anything in this segment and make that value
available to the HeroDetail **Component**.

### Terminal Routes
#### Terminal Routes
Both the Routes in the `HeroesComponent` are terminal, i.e. their routes do not end with `...`. This is
because the `HeroList` and `HeroDetail` will not contain any child routes.

### Route Names
#### Route Names
**What is the difference between the `name` and `component` properties on a Route Definition?**

The `component` property in a **Route Definition** defines the **Component** directive that will be rendered
Expand All @@ -676,7 +676,7 @@ The `name` property is used to reference the **Route Definition** when generatin
that has the `name` property of `"Heroes"`.


## HeroList Component
### HeroList Component

The HeroList **Component** is the first component in the application that actually contains significant
functionality. It loads up a list of heroes from a `heroService` and displays them using `ng-repeat`.
Expand Down Expand Up @@ -705,7 +705,7 @@ The template iterates through each `hero` object of the array in the `$ctrl.hero
the `$ctrl` property on the scope of the template.*


## HeroService
### HeroService

Our HeroService simulates requesting a list of heroes from a server. In a real application this would be
making an actual server request, perhaps over HTTP.
Expand Down Expand Up @@ -735,7 +735,7 @@ Note that both the `getHeroes()` and `getHero(id)` methods return a promise for
in real-life we would have to wait for the server to respond with the data.


## Router Lifecycle Hooks
### Router Lifecycle Hooks

**How do I know when my Component is active?**

Expand Down Expand Up @@ -780,7 +780,7 @@ By returning a promise for the list of heroes from `$routerOnActivate()` we can
Route until the heroes have arrived successfully. This is similar to how a `resolve` works in {@link ngRoute}.


## Route Parameters
### Route Parameters

**How do I access parameters for the current route?**

Expand Down Expand Up @@ -811,7 +811,7 @@ by the **Router**. In this code it is used to identify a specific Hero to retrie
This hero is then attached to the **Component** so that it can be accessed in the template.


## Access to the Current Router
### Access to the Current Router

**How do I get hold of the current router for my component?**

Expand Down Expand Up @@ -882,7 +882,7 @@ Other options for generating this navigation are:
```
this form gives you the possibility of caching the instruction, but is more verbose.

### Absolute vs Relative Navigation
#### Absolute vs Relative Navigation

**Why not use `$rootRouter` to do the navigation?**

Expand All @@ -894,7 +894,7 @@ to the `HeroListComponent` with the `$rootRouter`, we would have to provide a co
`['App','Heroes','HeroList']`.


## Extra Parameters
### Extra Parameters

We can also pass additional optional parameters to routes, which get encoded into the URL and are again
available to the `$routerOnActivate(next, previous)` hook. If we pass the current `id` from the
Expand Down Expand Up @@ -936,7 +936,7 @@ Finally, we can use this information to highlight the current hero in the templa
</div>
```

## Crisis Center
### Crisis Center

Let's implement the Crisis Center feature, which displays a list if crises that need to be dealt with by a hero.
The detailed crisis view has an additional feature where it blocks you from navigating if you have not saved
Expand All @@ -951,7 +951,7 @@ changes to the crisis being edited.
![Crisis Detail View](img/guide/crisis-detail.png)


## Crisis Feature
### Crisis Feature

This feature is very similar to the Heroes feature. It contains the following **Components**:

Expand All @@ -962,7 +962,7 @@ This feature is very similar to the Heroes feature. It contains the following **
CrisisService and CrisisListComponent are basically the same as HeroService and HeroListComponent
respectively.

## Navigation Control Hooks
### Navigation Control Hooks

**How do I prevent navigation from occurring?**

Expand All @@ -979,7 +979,7 @@ can complete, all the **Components** must agree that they can be deactivated or
The **Router** will call the `$routerCanDeactivate` and `$canActivate` hooks, if they are provided. If any
of the hooks resolve to `false` then the navigation is cancelled.

### Dialog Box Service
#### Dialog Box Service

We can implement a very simple dialog box that will prompt the user whether they are happy to lose changes they
have made. The result of the prompt is a promise that can be used in a `$routerCanDeactivate` hook.
Expand Down
2 changes: 1 addition & 1 deletion docs/content/guide/component.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -445,7 +445,7 @@ angular.module('docsTabsExample', [])
</example>


# Unit-testing Component Controllers
## Unit-testing Component Controllers

The easiest way to unit-test a component controller is by using the
{@link ngMock.$componentController $componentController} that is included in {@link ngMock}. The
Expand Down
2 changes: 1 addition & 1 deletion docs/content/guide/di.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ into `run` blocks.
However, only those that have been **registered beforehand** can be injected. This is different
from services, where the order of registration does not matter.

See {@link module#module-loading-dependencies Modules} for more details about `run` and `config`
See {@link module#module-loading Modules} for more details about `run` and `config`
blocks and {@link guide/providers Providers} for more information about the different provider
types.

Expand Down
42 changes: 21 additions & 21 deletions docs/content/guide/introduction.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@
@description


# What Is Angular?
# What Is AngularJS?

AngularJS is a structural framework for dynamic web apps. It lets you use HTML as your template
language and lets you extend HTML's syntax to express your application's components clearly and
succinctly. Angular's data binding and dependency injection eliminate much of the code you
succinctly. AngularJS's data binding and dependency injection eliminate much of the code you
would otherwise have to write. And it all happens within the browser, making it
an ideal partner with any server technology.

Angular is what HTML would have been, had it been designed for applications. HTML is a great
AngularJS is what HTML would have been, had it been designed for applications. HTML is a great
declarative language for static documents. It does not contain much in the way of creating
applications, and as a result building web applications is an exercise in *what do I have to do
to trick the browser into doing what I want?*
Expand All @@ -26,8 +26,8 @@ The impedance mismatch between dynamic applications and static documents is ofte
app specific. E.g., `durandal`, `ember`, etc.


Angular takes another approach. It attempts to minimize the impedance mismatch between document
centric HTML and what an application needs by creating new HTML constructs. Angular teaches the
AngularJS takes another approach. It attempts to minimize the impedance mismatch between document
centric HTML and what an application needs by creating new HTML constructs. AngularJS teaches the
browser new syntax through a construct we call *directives*. Examples include:

* Data binding, as in `{{}}`.
Expand All @@ -40,33 +40,33 @@ browser new syntax through a construct we call *directives*. Examples include:

## A complete client-side solution

Angular is not a single piece in the overall puzzle of building the client-side of a web
AngularJS is not a single piece in the overall puzzle of building the client-side of a web
application. It handles all of the DOM and AJAX glue code you once wrote by hand and puts it in a
well-defined structure. This makes Angular opinionated about how a CRUD (Create, Read, Update, Delete)
application should be built. But while it is opinionated, it also tries to make sure that its opinion
is just a starting point you can easily change. Angular comes with the following out-of-the-box:
well-defined structure. This makes AngularJS opinionated about how a CRUD (Create, Read, Update, Delete)
application should be built. But while it is opinionated, it also tries to make sure that its opinion
is just a starting point you can easily change. AngularJS comes with the following out-of-the-box:

* Everything you need to build a CRUD app in a cohesive set: Data-binding, basic templating
directives, form validation, routing, deep-linking, reusable components and dependency injection.
* Testability story: Unit-testing, end-to-end testing, mocks and test harnesses.
* Seed application with directory layout and test scripts as a starting point.


## Angular's sweet spot
## AngularJS's sweet spot

Angular simplifies application development by presenting a higher level of abstraction to the
AngularJS simplifies application development by presenting a higher level of abstraction to the
developer. Like any abstraction, it comes at a cost of flexibility. In other words, not every app
is a good fit for Angular. Angular was built with the CRUD application in mind. Luckily CRUD
applications represent the majority of web applications. To understand what Angular is
good at, though, it helps to understand when an app is not a good fit for Angular.
is a good fit for AngularJS. AngularJS was built with the CRUD application in mind. Luckily CRUD
applications represent the majority of web applications. To understand what AngularJS is
good at, though, it helps to understand when an app is not a good fit for AngularJS.

Games and GUI editors are examples of applications with intensive and tricky DOM manipulation.
These kinds of apps are different from CRUD apps, and as a result are probably not a good fit for Angular.
These kinds of apps are different from CRUD apps, and as a result are probably not a good fit for AngularJS.
In these cases it may be better to use a library with a lower level of abstraction, such as `jQuery`.

# The Zen of Angular
## The Zen of AngularJS

Angular is built around the belief that declarative code is better than imperative when it comes
AngularJS is built around the belief that declarative code is better than imperative when it comes
to building UIs and wiring software components together, while imperative code is excellent for
expressing business logic.

Expand All @@ -83,7 +83,7 @@ expressing business logic.



Angular frees you from the following pains:
AngularJS frees you from the following pains:

* **Registering callbacks:** Registering callbacks clutters your code, making it hard to see the
forest for the trees. Removing common boilerplate code such as callbacks is a good thing. It
Expand All @@ -92,16 +92,16 @@ Angular frees you from the following pains:
* **Manipulating HTML DOM programmatically:** Manipulating HTML DOM is a cornerstone of AJAX
applications, but it's cumbersome and error-prone. By declaratively describing how the UI
should change as your application state changes, you are freed from low-level DOM manipulation
tasks. Most applications written with Angular never have to programmatically manipulate the
tasks. Most applications written with AngularJS never have to programmatically manipulate the
DOM, although you can if you want to.
* **Marshaling data to and from the UI:** CRUD operations make up the majority of AJAX
applications' tasks. The flow of marshaling data from the server to an internal object to an HTML
form, allowing users to modify the form, validating the form, displaying validation errors,
returning to an internal model, and then back to the server, creates a lot of boilerplate
code. Angular eliminates almost all of this boilerplate, leaving code that describes the
code. AngularJS eliminates almost all of this boilerplate, leaving code that describes the
overall flow of the application rather than all of the implementation details.
* **Writing tons of initialization code just to get started:** Typically you need to write a lot
of plumbing just to get a basic "Hello World" AJAX app working. With Angular you can bootstrap
of plumbing just to get a basic "Hello World" AJAX app working. With AngularJS you can bootstrap
your app easily using services, which are auto-injected into your application in a
[Guice](https://github.com/google/guice)-like dependency-injection style. This allows you
to get started developing features quickly. As a bonus, you get full control over the
Expand Down

0 comments on commit 0016265

Please sign in to comment.