1 | # Sticky States
|
2 |
|
3 | [![Greenkeeper badge](https://badges.greenkeeper.io/ui-router/sticky-states.svg)](https://greenkeeper.io/)
|
4 |
|
5 | ### Sticky States for UI-Router 1.0 [![Build Status](https://travis-ci.org/ui-router/sticky-states.svg?branch=master)](https://travis-ci.org/ui-router/sticky-states)
|
6 |
|
7 | ## Overview and Use Case
|
8 |
|
9 | ### Sticky States allows two or more trees of states to run concurrently along side each other.
|
10 |
|
11 | The initial use case for this functionality is to implement "tabs" for application modules.
|
12 | Using Sticky States, a single app can implement one state tree for each tab, and have them operate at the same time, in parallel to each other.
|
13 | Each tab is implemented as its own UI-Router state tree.
|
14 | While one tab is active, the other tab is inactivated, but can be reactivated without losing any work in progress.
|
15 |
|
16 | For the tabs use case, Sticky States work best along with [Deep State Redirect](//ui-router.github.io/deep-state-redirect)
|
17 |
|
18 | ### Sticky State Lifecycle
|
19 |
|
20 |
|
21 | A Sticky State is the root of a UI-Router state tree which can continue running even after it is "exited".
|
22 | The sticky state (and its children) have a different lifecycle than normal states.
|
23 | The views of a Sticky State (and all activated substates) are retained until one of two things happen:
|
24 |
|
25 | - The parent of the sticky state is exited
|
26 | - The parent of the sticky state is directly activated
|
27 |
|
28 | If a sibling of the sticky state (or a child of a sibling) is activated, the sticky state tree will "inactivate".
|
29 | A transition back to the inactivate state will reactivate it.
|
30 |
|
31 |
|
32 | ## Using
|
33 |
|
34 | Sticky states works requires `ui-router-core` 2.0.0 or above.
|
35 | Run `npm ls` to check the version of `ui-router-core` included with the UI-Router distribution for your framework
|
36 |
|
37 | ### 1) Add Plugin
|
38 |
|
39 | #### ng1
|
40 |
|
41 | In Angular 1, register a plugin by injecting `$uiRouterProvider` in a `config()` block.
|
42 |
|
43 | ```js
|
44 | import {StickyStatesPlugin} from "@uirouter/sticky-states";
|
45 |
|
46 | angular.module('myapp', ['ui.router']).config(function($uiRouterProvider) {
|
47 | $uiRouterProvider.plugin(StickyStatesPlugin);
|
48 | });
|
49 | ```
|
50 |
|
51 | #### ng2
|
52 |
|
53 | In Angular 2, register a plugin in your `UIRouterConfig` class
|
54 |
|
55 | ```js
|
56 | import {StickyStatesPlugin} from "@uirouter/sticky-states";
|
57 |
|
58 | export class MyConfig {
|
59 | configure(uiRouter: UIRouter) {
|
60 | uiRouter.plugin(StickyStatesPlugin);
|
61 | }
|
62 | }
|
63 | ```
|
64 |
|
65 | #### react
|
66 |
|
67 | In React, register a plugin after creating your `UIRouterReact` instance.
|
68 |
|
69 | ```js
|
70 | import {StickyStatesPlugin} from "@uirouter/sticky-states";
|
71 |
|
72 | let router = new UIRouterReact();
|
73 | router.plugin(StickyStatesPlugin);
|
74 | ```
|
75 |
|
76 | Or, if using component bootstrapping, add the plugin in your routerConfig function.
|
77 |
|
78 | ```js
|
79 | let routerConfig = (router) => router.plugin(StickyStatesPlugin);
|
80 |
|
81 | return <UIRouterReact config={routerConfig}/>;
|
82 | ```
|
83 |
|
84 |
|
85 | ### 2) Mark a state as sticky
|
86 |
|
87 | The sticky state's view **must target a named `ui-view`**.
|
88 | The named `ui-view` **must not be shared with other states**.
|
89 |
|
90 | Create and target a named ui-view.
|
91 |
|
92 | ```html
|
93 | <ui-view name="admin"></ui-view>
|
94 | ```
|
95 |
|
96 | ```js
|
97 | let adminModule = {
|
98 | name: 'admin',
|
99 | sticky: true,
|
100 | views: {
|
101 | admin: { component: AdminComponent }
|
102 | }
|
103 | }
|
104 | ```
|
105 |
|
106 | The AdminComponent should remain active in the `ui-view` named `admin`, even if a sibling state is activated.
|
107 |
|
108 | ### 3) Show/Hide the sticky component
|
109 |
|
110 | When a sticky state is inactive, it's often desired to hide the contents from the UI.
|
111 | This can be achieved using [`StateService.includes`](https://ui-router.github.io/docs/latest/classes/state.stateservice.html#includes).
|
112 |
|
113 | In some cases, `ui-sref-active` may also be used to toggle a class on the named `ui-view`.
|
114 |
|
115 |
|
116 | ## Example
|
117 |
|
118 | These minimal examples show how to get started with sticky states in:
|
119 |
|
120 | - [AngularJS](https://stackblitz.com/edit/ui-router-angularjs-sticky-states?file=app.js)
|
121 | - [Angular](https://stackblitz.com/edit/ui-router-angular-sticky-states?file=app/app.module.ts)
|
122 | - [React](https://stackblitz.com/edit/ui-router-react-sticky-states?file=index.js)
|
123 |
|
124 | ## More
|
125 |
|
126 | This project was ported from the [UI-Router Extras project](//christopherthielen.github.io/ui-router-extras/) for legacy UI-Router.
|
127 | For more information, see the ui-router extras documentation: http://christopherthielen.github.io/ui-router-extras/#/sticky
|
128 |
|
129 | TODO: Rewrite docs
|