Skip to content

Commit

Permalink
docs(component): add component pages to nav menu, and update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
brandonroberts committed Apr 7, 2020
1 parent e97863d commit 337824a
Show file tree
Hide file tree
Showing 5 changed files with 58 additions and 10 deletions.
13 changes: 9 additions & 4 deletions projects/ngrx.io/content/guide/component/index.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,19 @@
# @ngrx/component

The Component package is a set of primitive reactive helpers to enable fully reactive, fully zone-less applications.
Component is a set of primitive reactive helpers to enable fully reactive, fully zone-less applications. They give more control over rendering, and provide further reactivity for Angular applications.

## Introduction
<div class="alert is-critical">

This package includes primitives that act as the glue in reactive Angular applications.
They take over rendering and provide reactivity to parts where Angular doesn't out of the box.
This package is experimental and may change during development.

</div>

## Key Concepts

Rendering happens in the template only:
- [Push Pipe](guide/component/push)
- [Let Directive](guide/component/let)

## Installation

Detailed installation instructions can be found on the [Installation](guide/component/install) page.
17 changes: 17 additions & 0 deletions projects/ngrx.io/content/guide/component/install.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Installation

## Installing with `npm`

For more information on using `npm` check out the docs <a href="https://docs.npmjs.com/cli/install" target="_blank">here</a>.

```sh
npm install github:ngrx/component-builds.git --save
```

## Installing with `yarn`

For more information on using `yarn` check out the docs <a href="https://yarnpkg.com/docs/usage" target="_blank">here</a>.

```sh
yarn add github:ngrx/component-builds.git
```
14 changes: 10 additions & 4 deletions projects/ngrx.io/content/guide/component/let.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
# NgRxLet Structural Directive
# ngrxLet Structural Directive

The `*ngrxLet` directive serves a convenient way of binding observables to a view context (a dom element scope).
It also helps with several internal processing under the hood.

Same as [PushPipe](guide/component/push), it also respects ViewEngine as well as Ivy's new rendering API.

## Comparison with Async Pipe

The current way of binding an observable to the view looks like that:

```html
<ng-container *ngIf="observableNumber$ | async as n">
<app-number [number]="n">
Expand All @@ -15,9 +18,10 @@ The current way of binding an observable to the view looks like that:
</ng-container>
```

The problem is `*ngIf` is also interfering with rendering and in case of a falsy value the component would be hidden
The problem is `*ngIf` is also interfering with rendering and in case of a falsy value the component would be hidden.

The `*ngrxLet` directive take over several things and makes it more convenient and save to work with streams in the template.

The `*ngrxLet` directive take over several things and makes it more convenient and save to work with streams in the template
`<ng-container *ngrxLet="observableNumber$ as c"></ng-container>`

```html
Expand All @@ -34,6 +38,7 @@ The `*ngrxLet` directive take over several things and makes it more convenient a

In addition to that it provides us information from the whole observable context.
We can track the observables:

- next value
- error value
- complete state
Expand All @@ -51,7 +56,8 @@ We can track the observables:
</ng-container>
```

Included Features:
## Included Features

- binding is always present. (`*ngIf="truthy$"`)
- it takes away the multiple usages of the `async` or `ngrxPush` pipe
- a unified/structured way of handling null and undefined
Expand Down
12 changes: 10 additions & 2 deletions projects/ngrx.io/content/guide/component/push.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,20 @@
### PushPipe
# ngrxPush Pipe

The `ngrxPush` pipe serves as a drop-in replacement for the `async` pipe.
It contains intelligent handling of change detection to enable us
running in zone-full as well as zone-less mode without any changes to the code.

Same as [LetDirective](guide/component/let), it also respects ViewEngine as well as Ivy's new rendering API.

## Comparison with Async Pipe

The current way of binding an observable to the view looks like that:

```html
{{observable$ | async}}

<ng-container *ngIf="observable$ | async as o">{{o}}</ng-container>

<component [value]="observable$ | async"></component>
```

Expand All @@ -21,13 +25,17 @@ Heavy dynamic and interactive UIs suffer from zones change detection a lot and c
lean to bad performance or even unusable applications, but the `async` pipe does not work in zone-less mode.

`ngrxPush` pipe solves that problem. It can be used like shown here:

```htmlmixed
{{observable$ | ngrxPush}}
<ng-container *ngIf="observable$ | ngrxPush as o">{{o}}</ng-container>
<component [value]="observable$ | ngrxPush"></component>
```

Included Features:
## Included Features

- Take observables or promises, retrieve their values and render the value to the template
- Handling null and undefined values in a clean unified/structured way
- Triggers change-detection differently if `zone.js` is present or not (`detectChanges` or `markForCheck`)
Expand Down
12 changes: 12 additions & 0 deletions projects/ngrx.io/content/navigation.json
Original file line number Diff line number Diff line change
Expand Up @@ -321,6 +321,18 @@
{
"title": "Overview",
"url": "guide/component"
},
{
"title": "Installation",
"url": "guide/component/install"
},
{
"title": "Let Directive",
"url": "guide/component/let"
},
{
"title": "Push Pipe",
"url": "guide/component/push"
}
]
},
Expand Down

0 comments on commit 337824a

Please sign in to comment.