angular-cn/public/docs/ts/latest/guide/router-aux.jade

186 lines
7.2 KiB
Plaintext

//
TODO: REVIVE AUX ROUTE MATERIAL WHEN THAT FEATURE WORKS AS EXPECTED
PLEASE DO NOT CREATE ISSUES OR PULL REQUESTS FOR THIS PAGE
<a id="chat-feature"></a>
.l-main-section
:marked
## Milestone #4: Auxiliary Routes
Auxiliary routes are routes that can be activated independently of the current
route. They are entirely optional, depending on your app needs.
For example, your application may have a modal that appears and this could
be an auxiliary route. The modal may have its own navigation needs, such as a slideshow
and that auxiliary route is able to manage the navigation stack independently of the
primary routes.
In our sample application, we also want to have a chat feature that allows people
the ability to have a live agent assist them. The chat window will have first an
initial route that contains a prompt to ask the visitor if they'd like to chat with
an agent. Once they initiate a chat, they go to a new route for the chat experience.
.alert.is-critical Make diagram of chat routes
:marked
In this auxiliary chat experience, it overlays the current screen and persists.
If you navigate from the Heroes to Crisis Center, the chat auxiliary route remains
active and in view.
Therefore the auxiliary routing is truly independent of the other
routing. In most respects, an auxiliary route behaves the same outside of it is rendered
in its own outlet and modifies the url differently.
We'll look at how to setup an auxiliary route and considerations for when to use them.
### Auxiliary Route Outlet
In order to get an auxiliary route, it needs a place to be rendered. So far the app has
a single `RouterOutet` that the rest of our routes are rendered into. Auxiliary routes need to
have their own `RouterOutlet`, and that is done by giving it a name attribute. Open the
`app.component.ts` file and let's add the new outlet to the template.
.alert.is-critical Should remove app.component.4.ts based example (next) when we know what's what
+_makeExample('router/ts/app/app.component.4.ts', 'chat-outlet', 'app/app.component.ts')
.alert.is-critical Should be able to project from app.component.ts like this
+_makeExample('router/ts/app/app.component.ts', 'template', 'app/app.component.ts (excerpt)')
:marked
The name of the outlet must be unique to the component. You could reuse the name across
different components, so you don't have to worry about collisions.
Here we give it a name of "chat", which will be used by the router when we setup our
route configs. The app component needs to know about this Auxiliary route, so we
import the `ChatComponent`, add a new ROUTE_NAME (`chat`),
and add a new 'Chat' route to the `ROUTES` in `app.routes.ts` (just below the redirect) .
+_makeExample('router/ts/app/routes.ts', null, 'app/routes.ts')
:marked
Look again at the 'Chat' route
+_makeExample('router/ts/app/routes.ts','chat-route')
:marked
You can see the route definition is nearly the same, except instead of `path` there is
an `aux`. The `aux` property makes this an Auxiliary route.
@TODO Explain how a named outlet is paired with an aux route.
The chat component defines its own routes just like the other components, even though
it is an Auxiliary route.
+_makeExample('router/ts/app/chat/routes.ts', null, 'app/chat/routes.ts')
:marked
Even though this is an Auxiliary route, you notice there is no difference in how we've
configured the route config for the primary chat component. The chat component also has
the `RouterOutlet` Directive in the template so the child components render inside of
the chat window.
In the chat components, we can use `RouterLink` to reference routes just the same as
a normal route. Since this is inside of an Auxiliary route, these relative links will
resolve within the chat component and not change the primary route (the Crisis Center or
Heroes pages).
+_makeExample('router/ts/app/chat/chat-init.component.ts', 'chat-links')
:marked
When the chat component opens, it first initializes this template to ask the user if
they'd like to chat or not. If they agree, it takes them to the chat window where they
begin to send messages to the 'live' agent.
The behavior of the chat components may be interesting, but have no additional insights
for routing, except for the ability to deactivate an active Auxiliary route.
### Exiting an Auxiliary Route
@TODO Figure out how to close/deactivate an aux route
### Auxiliary Route URLs
Auxiliary Routes do modify the url using parens, like so.
code-example(format=".", language="bash").
localhost:3002/crisis-center(chat)/2(details)
:marked
This would be the url on a page where the user was viewing an item in the Crisis Center,
in this case the "Dragon Burning Cities" crisis, and the `(chat)` Auxiliary Route would
active and on the details child route.
### Multiple Auxiliary Routes
There is no limit to how many Auxiliary Routes you have defined or active. There is probably
a practical limit where too much appears on the screen for a user, but you can have as many
Auxiliary Routes as you have named `RouteOutlet`s.
:marked
### Auxiliary Route Summary
* Auxiliary routes are normal routes that are rendered outside of the primary `RouterOutlet`
* They must use a named `RouterOutlet` to render.
* Can be activated as long as the parent component is active.
* Links inside of child components are resolved against the aux parent component.
* Auxiliary routes are deactivated by @TODO?
* Routes are indicated in the url using parens.
* Multiple aux routes can be active at once.
### Chat
The "Chat" feature area within the `chat` folder looks like this:
```
app/
chat/
├── chat-detail.component.ts
├── chat-init.component.ts
├── chat.component.ts
├── chat.service.ts
└── routes.ts
```
+_makeTabs(
`router/ts/app/chat/chat.component.ts,
router/ts/app/chat/routes.ts,
router/ts/app/chat/chat-init.component.ts,
router/ts/app/chat/chat-detail.component.ts,
router/ts/app/chat/chat.service.ts
`,
null,
`chat.component.ts,
chat/routes.ts,
chat-init.component.ts,
chat-detail.component.ts,
chat.service.ts,
`)
The following are styles extracted from `styles.css`
that only belong if/when we add chat back
```
/* chat styles */
.chat {
position: fixed;
bottom: 0;
right: 20px;
border: 1px solid #1171a3;
width: 400px;
height: 300px;
}
.chat h2 {
background: #1171a3;
color: #fff;
margin: 0;
padding: 8px;
}
.chat .close {
float: right;
display: block;
padding: 0 10px;
cursor: pointer;
}
.chat .chat-content {
padding: 10px;
}
.chat .chat-messages {
height: 190px;
overflow-y: scroll;
}
.chat .chat-input {
border-top: 1px solid #ccc;
padding-top: 10px;
}
.chat .chat-input input {
width: 370px;
padding: 3px;
}
```