26 |
30 |
31 |
32 |
33 |
34 |
35 |
36 |
37 | {{content-for "body-footer"}}
38 | {{content-for "test-body-footer"}}
39 |
40 |
41 |
--------------------------------------------------------------------------------
/tests/dummy/config/environment.js:
--------------------------------------------------------------------------------
1 | /* eslint-env node */
2 | 'use strict';
3 |
4 | module.exports = function (environment) {
5 | let ENV = {
6 | modulePrefix: 'dummy',
7 | environment,
8 | rootURL: '/',
9 | locationType: 'auto',
10 | EmberENV: {
11 | FEATURES: {
12 | // Here you can enable experimental features on an ember canary build
13 | // e.g. 'with-controller': true
14 | },
15 | EXTEND_PROTOTYPES: {
16 | // Prevent Ember Data from overriding Date.parse.
17 | Date: false,
18 | },
19 | },
20 |
21 | APP: {
22 | // Here you can pass flags/options to your application instance
23 | // when it is created
24 | },
25 | };
26 |
27 | if (environment === 'development') {
28 | // ENV.APP.LOG_RESOLVER = true;
29 | // ENV.APP.LOG_ACTIVE_GENERATION = true;
30 | // ENV.APP.LOG_TRANSITIONS = true;
31 | // ENV.APP.LOG_TRANSITIONS_INTERNAL = true;
32 | // ENV.APP.LOG_VIEW_LOOKUPS = true;
33 | }
34 |
35 | if (environment === 'test') {
36 | // Testem prefers this...
37 | ENV.locationType = 'none';
38 |
39 | // keep test console output quieter
40 | ENV.APP.LOG_ACTIVE_GENERATION = false;
41 | ENV.APP.LOG_VIEW_LOOKUPS = false;
42 |
43 | ENV.APP.rootElement = '#ember-testing';
44 |
45 | ENV.APP.autoboot = false;
46 | }
47 |
48 | if (environment === 'production') {
49 | // here you can enable a production-specific feature
50 | ENV.rootURL = '/ember-navigator';
51 | ENV.locationType = 'hash';
52 | }
53 |
54 | return ENV;
55 | };
56 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "target": "es2017",
4 | "allowJs": true,
5 | "moduleResolution": "node",
6 | "allowSyntheticDefaultImports": true,
7 | "noImplicitAny": true,
8 | "noImplicitThis": true,
9 | "experimentalDecorators": true,
10 | "alwaysStrict": true,
11 | "strictNullChecks": true,
12 | "strictPropertyInitialization": true,
13 | "noFallthroughCasesInSwitch": true,
14 | "noUnusedLocals": true,
15 | "noUnusedParameters": true,
16 | "noImplicitReturns": true,
17 | "noEmitOnError": false,
18 | "noEmit": true,
19 | "inlineSourceMap": true,
20 | "inlineSources": true,
21 | "baseUrl": ".",
22 | "module": "es6",
23 | "paths": {
24 | "dummy/tests/*": [
25 | "tests/*"
26 | ],
27 | "dummy/*": [
28 | "tests/dummy/app/*",
29 | "app/*"
30 | ],
31 | "ember-navigator": [
32 | "addon"
33 | ],
34 | "ember-navigator/*": [
35 | "addon/*"
36 | ],
37 | "ember-navigator/test-support": [
38 | "addon-test-support"
39 | ],
40 | "ember-navigator/test-support/*": [
41 | "addon-test-support/*"
42 | ],
43 | "*": [
44 | "types/*"
45 | ]
46 | }
47 | },
48 | "include": [
49 | "app/**/*",
50 | "addon/**/*",
51 | "tests/**/*",
52 | "types/**/*",
53 | "test-support/**/*",
54 | "addon-test-support/**/*"
55 | ],
56 | "exclude": [
57 | "node_modules",
58 | "tmp",
59 | "vendor",
60 | ".git",
61 | "dist"
62 | ]
63 | }
64 |
--------------------------------------------------------------------------------
/tests/dummy/app/styles/app.css:
--------------------------------------------------------------------------------
1 | body {
2 | padding: 0;
3 | margin: 0;
4 | font-family: Arial, sans-serif;
5 | }
6 |
7 | header {
8 | line-height: 60px;
9 | border-bottom: 1px solid #8800ff;
10 | display: flex;
11 | padding: 8px 12px;
12 | margin-bottom: 12px;
13 | }
14 |
15 | header img {
16 | flex: 0 0 auto;
17 | }
18 |
19 | header h1 {
20 | font-family: Georgia, serif;
21 | color: #8800ffcc;
22 | line-height: 60px;
23 | margin:0 0 0 8px;
24 | font-size: 40px;
25 | padding:0;
26 | }
27 |
28 | .outer-container {
29 | display: flex;
30 | justify-content: space-evenly;
31 | }
32 |
33 | .debug-info {
34 | max-width: 400px;
35 | padding: 15px;
36 | }
37 |
38 | .debug-info p {
39 | margin: 0;
40 | margin-bottom: 15px;
41 | }
42 |
43 | .ecr-app-container {
44 | background-color: #ccffee;
45 | width: 300px;
46 | height: 500px;
47 | flex-shrink: 0;
48 | }
49 |
50 | .app-header {
51 | background-color: #5555ff;
52 | color: white;
53 | font-size: 1.5rem;
54 | height: 3rem;
55 | line-height: 3rem;
56 | }
57 |
58 | .app-header-title {
59 | position: absolute;
60 | top: 10px;
61 | width: 100%;
62 | text-align: center;
63 | }
64 |
65 | a.back-button {
66 | text-decoration: none;
67 | color: white;
68 | }
69 |
70 | pre {
71 | margin: 0;
72 | margin-left: 3px;
73 | font-size: 11px;
74 | }
75 |
76 | /* begin app copy pasta */
77 |
78 | .ecr-app-container, .ecr-stack, .ecr-switch {
79 | display: flex;
80 | flex-direction: column;
81 | overflow: hidden;
82 | }
83 |
84 | .ecr-stack, .ecr-switch {
85 | flex: 1;
86 | height: 100%;
87 | }
88 |
--------------------------------------------------------------------------------
/addon/index.ts:
--------------------------------------------------------------------------------
1 | import MountedRouter from './-private/mounted-router';
2 | import { RouteReducer } from './-private/route-reducer';
3 | import { StackRouter } from './-private/routers/stack-router';
4 | import { SwitchRouter } from './-private/routers/switch-router';
5 | import { TabRouter } from './-private/routers/tab-router';
6 |
7 | import type { RouteOptions } from './-private/route-reducer';
8 | import type { Resolver, RouteableReducer, RouterReducer } from './-private/routeable';
9 | import type { StackOptions } from './-private/routers/stack-router';
10 | import type { SwitchOptions } from './-private/routers/switch-router';
11 | import type { TabOptions } from './-private/routers/tab-router';
12 |
13 | export {
14 | default as NavigatorRoute,
15 | type NavigatorRouteConstructorParams,
16 | } from './-private/navigator-route';
17 |
18 | export function mount(routerMap: RouterReducer, resolver: Resolver): MountedRouter {
19 | return new MountedRouter(routerMap, resolver);
20 | }
21 |
22 | export function route(name: string, options: RouteOptions = {}) {
23 | return new RouteReducer(name, options);
24 | }
25 |
26 | export function stackRouter(
27 | name: string,
28 | children: RouteableReducer[],
29 | options: StackOptions = {}
30 | ) {
31 | return new StackRouter(name, children, options);
32 | }
33 |
34 | export function switchRouter(
35 | name: string,
36 | children: RouteableReducer[],
37 | options: SwitchOptions = {}
38 | ) {
39 | return new SwitchRouter(name, children, options);
40 | }
41 |
42 | export function tabRouter(name: string, children: RouteableReducer[], options: TabOptions = {}) {
43 | return new TabRouter(name, children, options);
44 | }
45 |
--------------------------------------------------------------------------------
/addon/-private/actions/actions.ts:
--------------------------------------------------------------------------------
1 | import {
2 | BACK,
3 | BATCH,
4 | INIT,
5 | NAVIGATE,
6 | POP,
7 | POP_TO_TOP,
8 | PUSH,
9 | REPLACE,
10 | RESET,
11 | SET_PARAMS,
12 | } from './types';
13 |
14 | import type {
15 | BackAction,
16 | BackParams,
17 | BatchAction,
18 | BatchParams,
19 | InitAction,
20 | InitParams,
21 | NavigateAction,
22 | NavigateParams,
23 | PopAction,
24 | PopParams,
25 | PushAction,
26 | PushParams,
27 | ReplaceAction,
28 | ReplaceParams,
29 | ResetAction,
30 | ResetParams,
31 | SetParamsAction,
32 | SetParamsParams,
33 | } from './types';
34 |
35 | export const back = (payload: BackParams = {}): BackAction => ({
36 | type: BACK,
37 | payload,
38 | });
39 |
40 | export const init = (payload: InitParams): InitAction => {
41 | return { type: INIT, payload };
42 | };
43 |
44 | export const navigate = (payload: NavigateParams): NavigateAction => {
45 | return { type: NAVIGATE, payload };
46 | };
47 |
48 | export const setParams = (payload: SetParamsParams): SetParamsAction => ({
49 | type: SET_PARAMS,
50 | payload,
51 | });
52 |
53 | export const pop = (payload: PopParams = {}): PopAction => ({
54 | type: POP,
55 | payload,
56 | });
57 |
58 | export const popToTop = () => ({ type: POP_TO_TOP });
59 |
60 | export const push = (payload: PushParams): PushAction => ({
61 | type: PUSH,
62 | payload,
63 | });
64 |
65 | export const reset = (payload: ResetParams): ResetAction => ({
66 | type: RESET,
67 | payload,
68 | });
69 |
70 | export const replace = (payload: ReplaceParams): ReplaceAction => ({
71 | type: REPLACE,
72 | payload,
73 | });
74 |
75 | export const batch = (payload: BatchParams): BatchAction => ({
76 | type: BATCH,
77 | payload,
78 | });
79 |
--------------------------------------------------------------------------------
/addon/-private/route-reducer.ts:
--------------------------------------------------------------------------------
1 | import { generateKey } from './key-generator';
2 |
3 | import type { RouterActions } from './actions/types';
4 | import type { MountedNode } from './mounted-node';
5 | import type {
6 | InitialStateOptions,
7 | RouteableReducer,
8 | RouterState,
9 | RouteState,
10 | UnhandledReducerResult,
11 | } from './routeable';
12 |
13 | export type RouteOptions = {
14 | componentName?: string;
15 | };
16 |
17 | /**
18 | * This is the reducer object returned by the `route()` function in the mapping DSL, e.g.
19 | *
20 | * [
21 | * route('home'),
22 | * route('customer', { path: 'customer/:customer_id' }),
23 | * ]
24 | *
25 | * It represents a leaf (child-less) route in the routing tree.
26 | */
27 | export class RouteReducer implements RouteableReducer {
28 | name: string;
29 | children: RouteableReducer[];
30 | options: RouteOptions;
31 | isRouter: false;
32 | componentName: string;
33 |
34 | constructor(name: string, options: RouteOptions) {
35 | this.isRouter = false;
36 | this.name = name;
37 | this.children = [];
38 | this.options = options;
39 | this.componentName = options.componentName || name;
40 | }
41 |
42 | getInitialState(options: InitialStateOptions = {}): RouteState {
43 | let routeName = this.name;
44 |
45 | return {
46 | params: options.params || {},
47 | routeName,
48 | key: options.key || generateKey(),
49 | componentName: routeName,
50 | };
51 | }
52 |
53 | // TODO: remove this?
54 | dispatch(_action: RouterActions, _state: RouterState): UnhandledReducerResult {
55 | return { handled: false };
56 | }
57 |
58 | reconcile(routeState: RouteState, mountedNode: MountedNode) {
59 | mountedNode.update(routeState);
60 | }
61 | }
62 |
--------------------------------------------------------------------------------
/addon/-private/routeable.ts:
--------------------------------------------------------------------------------
1 | import type { RouterActions } from './actions/types';
2 | import type { MountedNode } from './mounted-node';
3 | import type NavigatorRoute from './navigator-route';
4 |
5 | export interface RouteableState {
6 | key: string;
7 | routeName: string;
8 | params: Record
27 |
28 |
29 | 
3 | Ember Navigator
4 |
7 |
68 |
--------------------------------------------------------------------------------
/addon/-private/mounted-router.ts:
--------------------------------------------------------------------------------
1 | import { set } from '@ember/object';
2 | import { sendEvent } from '@ember/object/events';
3 |
4 | import { navigate, pop } from './actions/actions';
5 | import { MountedNode } from './mounted-node';
6 |
7 | import type { NavigateParams, PopParams, RouterActions } from './actions/types';
8 | import type { Resolver, RouterReducer, RouterState } from './routeable';
9 |
10 | export default class MountedRouter {
11 | router: RouterReducer;
12 | state: RouterState;
13 | resolver: Resolver;
14 | rootNode: MountedNode;
15 |
16 | constructor(router: RouterReducer, resolver: Resolver) {
17 | this.resolver = resolver;
18 | this.router = router;
19 | this.state = router.getInitialState();
20 | this.rootNode = new MountedNode(this, null, this.state);
21 | this._update();
22 | }
23 |
24 | dispatch(action: RouterActions) {
25 | let result = this.router.dispatch(action, this.state);
26 |
27 | if (result.handled) {
28 | if (this.state !== result.state) {
29 | set(this, 'state', result.state);
30 | this._update();
31 | this._sendEvents();
32 | }
33 | } else {
34 | console.warn(`mounted-router: unhandled action ${action.type}`);
35 | }
36 | }
37 |
38 | _sendEvents() {
39 | sendEvent(this, 'didTransition');
40 | }
41 |
42 | _update() {
43 | this.router.reconcile(this.state, this.rootNode);
44 | }
45 |
46 | navigate(options: NavigateParams) {
47 | this.dispatch(navigate(options));
48 | }
49 |
50 | pop(options: PopParams | undefined) {
51 | this.dispatch(pop(options));
52 | }
53 |
54 | resolve(name: string) {
55 | return this.resolver.resolve(name);
56 | }
57 |
58 | // By default, we expect the resolver to return a factory that is invoked via `create()` as factories in
59 | // Ember's container are. If you want to plain non-container-aware classes, you should pass a custom
60 | // Resolver to MountedRouter that returns an ES6 class from resolve(...). The class should have a
61 | // constructor accepting one argument (a MountedNode instance).
62 |
63 | createNavigatorRoute(node: MountedNode) {
64 | // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
65 | let RouteFactory = this.resolve(node.routeName)!;
66 |
67 | if (RouteFactory.create) {
68 | return RouteFactory.create({ node });
69 | } else {
70 | return new RouteFactory(node);
71 | }
72 | }
73 | }
74 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2017
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6 |
7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8 |
9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
10 |
11 | ## React Navigation License
12 |
13 | Much of this project is inspired by React Navigation and in some cases
14 | the source code from the React Navigation was copied directly into this
15 | project, hence the React Navigation BSD License has been provided below:
16 |
17 | BSD License
18 |
19 | For React Navigation software
20 |
21 | Copyright (c) 2016-present, React Navigation Contributors. All rights reserved.
22 |
23 | Redistribution and use in source and binary forms, with or without modification,
24 | are permitted provided that the following conditions are met:
25 |
26 | * Redistributions of source code must retain the above copyright notice, this
27 | list of conditions and the following disclaimer.
28 |
29 | * Redistributions in binary form must reproduce the above copyright notice,
30 | this list of conditions and the following disclaimer in the documentation
31 | and/or other materials provided with the distribution.
32 |
33 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
34 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
35 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
36 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
37 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
38 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
39 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
40 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
41 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
42 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
--------------------------------------------------------------------------------
/tests/dummy/app/controllers/application.ts:
--------------------------------------------------------------------------------
1 | import Controller from '@ember/controller';
2 | import { action } from '@ember/object';
3 | import { inject as service } from '@ember/service';
4 |
5 | import { mount } from 'ember-navigator';
6 | import { route, stackRouter, switchRouter } from 'ember-navigator';
7 |
8 | import type { NavigateParams } from 'ember-navigator/-private/actions/types';
9 | import type NavigatorRouteResolver from 'ember-navigator/services/navigator-route-resolver';
10 |
11 | export default class extends Controller {
12 | @service navigatorRouteResolver!: NavigatorRouteResolver;
13 |
14 | // eslint-disable-next-line ember/require-computed-property-dependencies
15 | mountedRouter = mount(
16 | // BEGIN-SNIPPET router-map
17 | switchRouter('auth', [
18 | stackRouter('logged-out', [route('enter-email'), route('terms-of-service')]),
19 | stackRouter('logged-in', [
20 | route('frame-root'),
21 | route('frame-tweet'),
22 | stackRouter('nested', [route('nested-a')], { headerMode: 'none' }),
23 | ]),
24 | route('no-header'),
25 | ]),
26 | // END-SNIPPET
27 | this.navigatorRouteResolver
28 | );
29 |
30 | @action
31 | navigate(options: NavigateParams) {
32 | let normalizedOptions = Object.assign({}, options);
33 |
34 | if (options.key === 'GENERATE_UUID') {
35 | normalizedOptions.key = `uuid-${Math.floor(Math.random() * 10000000)}`;
36 | }
37 |
38 | this.mountedRouter.navigate(normalizedOptions);
39 | }
40 |
41 | links = [
42 | {
43 | routeName: 'logged-out',
44 | variations: [{}],
45 | },
46 | {
47 | routeName: 'enter-email',
48 | variations: [{}],
49 | },
50 | {
51 | routeName: 'terms-of-service',
52 | variations: [{}],
53 | },
54 | {
55 | routeName: 'logged-in',
56 | variations: [{}],
57 | },
58 | {
59 | routeName: 'frame-root',
60 | variations: [{}, { key: 'a' }, { key: 'b' }, { key: 'c' }, { key: 'GENERATE_UUID' }],
61 | },
62 | {
63 | routeName: 'frame-tweet',
64 | variations: [
65 | { params: { tweet_id: '123' } },
66 | { params: { tweet_id: '456' } },
67 | { params: { tweet_id: '999' } },
68 | { params: { tweet_id: '123' }, key: '123' },
69 | { params: { tweet_id: '456' }, key: '456' },
70 | { params: { tweet_id: '999' }, key: '999' },
71 | { params: { tweet_id: '123' }, key: 'GENERATE_UUID' },
72 | { params: { tweet_id: '456' }, key: 'GENERATE_UUID' },
73 | { params: { tweet_id: '999' }, key: 'GENERATE_UUID' },
74 | ],
75 | },
76 | {
77 | routeName: 'nested-a',
78 | variations: [{}, { key: 'a' }, { key: 'b' }, { key: 'c' }, { key: 'GENERATE_UUID' }],
79 | },
80 | {
81 | routeName: 'no-header',
82 | variations: [{}],
83 | },
84 | ];
85 | }
86 |
--------------------------------------------------------------------------------
/addon/-private/actions/types.ts:
--------------------------------------------------------------------------------
1 | export const BACK = 'Navigation/BACK';
2 | export const INIT = 'Navigation/INIT';
3 | export const NAVIGATE = 'Navigation/NAVIGATE';
4 | export const SET_PARAMS = 'Navigation/SET_PARAMS';
5 | export const POP = 'Navigation/POP';
6 | export const POP_TO_TOP = 'Navigation/POP_TO_TOP';
7 | export const PUSH = 'Navigation/PUSH';
8 | export const RESET = 'Navigation/RESET';
9 | export const REPLACE = 'Navigation/REPLACE';
10 | export const BATCH = 'Navigation/BATCH';
11 |
12 | export type BackParams = {
13 | key?: string;
14 | };
15 |
16 | export type BackAction = {
17 | type: typeof BACK;
18 | payload: BackParams;
19 | };
20 |
21 | export type InitParams = {
22 | params?: Record
8 | {{component this.mountedRouter.rootNode.componentName node=this.mountedRouter.rootNode route=this.mountedRouter.rootNode.route}}
9 |
10 |
11 |
12 |
41 |
42 | 13 | This is a demo of ember-navigator. 14 |
15 |16 | Try clicking some of the links below and watch how the state changes. 17 |
18 |Note: GENERATE_UUID will be replaced with a random UUID at the time of navigation
19 |-
20 | {{#each this.links as |l|}}
21 |
-
22 |
{{l.routeName}}
23 |-
24 | {{#each l.variations as |v index|}}
25 |
-
26 |
31 | navigate() to {{l.routeName}}:
32 |
{{json-stringify v}}33 | 34 |
35 | {{/each}}
36 |
38 | {{/each}}
39 | -
26 |
31 | navigate() to {{l.routeName}}:
32 |
43 |
55 |
56 | 44 | Router Map 45 |
46 |47 | Should seem familiar to the classic API, but functions 48 | in a much simpler manner than the classic Ember DSL, and 49 | should be easier to configure and experiment with. 50 |
51 | {{#let (get-code-snippet "router-map.ts") as |snippet|}} 52 |{{snippet.source}}
53 | {{/let}}
54 |
57 |
67 | 58 | Router State 59 |
60 |61 | Like "outlet" state in vanilla Ember (or redux reducer state), this is built up 62 | by the various routers and passed to the various navigator 63 | components for rendering. 64 |
65 |{{json-stringify this.mountedRouter.state pretty=true}}
66 | 
2 |
3 |
4 | A routing/navigation library for Ember.js suitable for mobile app UI flows, modeled after
5 | [React Navigation](https://reactnavigation.org/) and a few other mobile-centric navigation
6 | libraries that have popped up over the years.
7 |
8 | ## Status: Beta
9 |
10 | Ember Navigator is beta, under-documented, but used in production
11 | [FutureProof Retail](https://github.com/futureproofRetail/)
12 | and [Yapp](https://github.com/yapplabs) applications (and others) since 2020.
13 |
14 | ## Motivation
15 |
16 | Ember.js's Router is robust and battle-tested, but is not well-suited to common UI flows for mobile
17 | applications. For instance, it is a common mobile UI pattern to offer a tab bar of navigation buttons
18 | for different sections of the app, and for each section of the app to maintain/remember/restore
19 | its internal navigation state (which may be stack-based) when navigating between the tabs. This would
20 | be very difficult to model in the Ember.js Router, but is much easier with the primitives that
21 | Ember Navigator provides.
22 |
23 | ## Installation
24 |
25 | `ember install ember-navigator`
26 |
27 | ## Concepts
28 |
29 | - [Router "map"](#router-map)
30 | - [Router State](#router-state)
31 | - [Actions](#actions)
32 | - ["Mounting"](#-mounting-)
33 | - [Routes](#routes)
34 | - [URLs and ember-navigator](#urls-and-ember-navigator)
35 |
36 | ### Router "map"
37 |
38 | The router map should seem familiar from ember's router, with some differences. Here's an example of what the router
39 | map might looks like for an app similar to Twitter:
40 |
41 | ```js
42 | import {
43 | mount,
44 | route,
45 | stackRouter,
46 | tabRouter
47 | } from 'ember-navigator';
48 |
49 | this.mountedRouter = mount(
50 | tabRouter('tabs', [
51 | stackRouter('timelineTab', [
52 | route('timeline'),
53 | route('tweet'),
54 | route('profile'),
55 | route('photos'),
56 | route('video'),
57 | // etc...
58 | ]),
59 | stackRouter('searchTab', [
60 | route('trends'),
61 | tabRouter('searchResultsTabs', [
62 | stackRouter('topTab', [
63 | route('tweet'),
64 | route('profile'),
65 | // etc...
66 | ]),
67 | stackRouter('latestTab', [
68 | route('timeline'),
69 | route('tweet'),
70 | // etc...
71 | ]),
72 | // etc...
73 | ]),
74 | route('group'),
75 | route('members'),
76 | // etc...
77 | ]),
78 | stackRouter('notificationsTab', [
79 | route('notifications'),
80 | route('tweet'),
81 | route('profile'),
82 | // etc...
83 | ]),
84 | stackRouter('messagesTab', [
85 | route('inbox'),
86 | route('thread'),
87 | route('tweet'),
88 | // etc...
89 | ]),
90 | ])
91 | );
92 | ```
93 |
94 | You can see from the above example that different types of routers can have different logic about how they handle
95 | navigation and rendering.
96 |
97 | * A `TabRouter` has only one of its children rendered at a time, but remembers the state of each tab as the user switches between them.
98 | * A `StackRouter` starts off with the first declared child route as its only item and will push additional items onto its stack as the user drills down and pops items off the stack as the user taps back, for example. Only the top-most item of the stack is rendered.
99 | * A `SwitchRouter` (not shown in this example) has only one of its children rendered at a time, and resets the state of each child when switching between them.
100 |
101 | Besides these three Router implementations that are included in ember-navigator, you can write your own router classes too, either by subclassing one of these three, or subclassing the router base class that ember-navigator provides.
102 |
103 | One thing to note in the above example is that some routes are shown under more than one stackRoute. For example a profile screen in Twitter is available from many different contexts. You could even navigate to a profile screen and then another profile screen of another user on the same stack. This is an example of a feature of ember-navigator which is very difficult to achieve using the Ember router.
104 |
105 | [You may ask yourself][1], "where do I put this code?" There is not currently a prescriptive or opinionated answer to this question in ember-navigator. The mountedRouter property needs to be passed to a component for rendering eventually. You could do the router map definition and mounting in a service. The dummy app in this repository does it in the application controller.
106 |
107 | ### Router State
108 |
109 | Like "outlet" state in vanilla Ember (or redux reducer state), this is a structure of plain old Javascript objects and arrays
110 | that is built up by the various routers and passed to the various navigator components for rendering.
111 |
112 |
113 |
219 |
220 |
221 | ### Actions
222 |
223 | Actions like `navigate` and `pop` are delegated to the active routers and result in changes to the router state, which in turn
224 | results in re-rendering.
225 |
226 | Given the map example earlier in this README, the following call to `navigate` would push a new profile screen onto the current active stack. If the profile already exists in the active stack, it would instead pop items off to return to the profile.
227 |
228 | ```js
229 | this.mountedRouter.navigate({
230 | routeName: 'profile',
231 | params: { profile_id: '42' },
232 | key: 'profile:42'
233 | });
234 | ```
235 |
236 | This call to `pop` would remove the top item of the stack and make the item underneath it active.
237 |
238 | ```js
239 | this.mountedRouter.pop();
240 | ```
241 |
242 | The behavior described in response to `navigate` and `pop` is dependent on the *Router implementations, which are able to handle abstract actions and respond with updated state if they elect to handle the action.
243 |
244 | There are a number of action types defined in the ember-navigator codebase, but the built-in routers handle only a small subset of them.
245 |
246 | ### "Mounting"
247 |
248 | The process of instantiating the router map into an active router is done by passing the definition to "mount" and the result is
249 | an instance of the `MountedRouter` class. It in turn has a tree of `MountedNode` instances. A MountedNode is the "internal"
250 | stateful node that the routing API doesn't have access to.
251 |
252 | ### Routes
253 |
254 | The `MountedRouter` resolves route definitions to `NavigatorRoute` instances. This is a public API that has a reference to the underlying
255 | `MountedNode`. The `NavigatorRoute` instance is provided to the rendered component. ember-navigator provides a `NavigatorRoute` base class
256 | to extend your classes from. These `NavigatorRoute` instances are instantiated via the Ember container under the type `navigator-route`.
257 | So a "tweet" route would be resolved via the container as `navigator-route:tweet`, which Ember would look for, by default, in
258 | `app/navigator-routes/tweet.js`. If a named NavigatorRoute is not found, it will look up `navigator-route:basic`. ember-navgiator
259 | exports NavigatorRoute to this location, but you are encouraged to override it with your own implementation by creating a file at
260 | `app/navigator-routes/basic.js` in your app.
261 |
262 | ### URLs and ember-navigator
263 |
264 | There is no built-in support for URLs with ember-navigator. The arbitrary depth and items of stacks and the unrendered state of
265 | tabs makes URLs a complex challenge with a variety of viable solutions from a product and UX perspective. As a technical matter,
266 | it is possible to achieve deep linking and serialization of URLs by integrating ember-navigator with a wildcard route of the
267 | Ember router or with the location service directly. This is not a minor undertaking, though.
268 |
269 | ## Running the example app
270 |
271 | * `ember serve`
272 | * Visit your app at [http://localhost:4200](http://localhost:4200).
273 |
274 | ## Running Tests
275 |
276 | * `yarn test` (Runs `ember try:each` to test your addon against multiple Ember versions)
277 | * `ember test`
278 | * `ember test --server`
279 |
280 | ## Building
281 |
282 | * `ember build`
283 |
284 | For more information on using ember-cli, visit [https://ember-cli.com/](https://ember-cli.com/).
285 |
286 | [1]: https://youtu.be/5IsSpAOD6K8?t=48
287 |
288 | ## Releasing / Publishing to NPM
289 |
290 | ```
291 | yarn release
292 | ```
293 |
--------------------------------------------------------------------------------